Recurring Consumers and Subscriptions
The Recurring API is always input as CGI XML. It lets you input and modify consumers and subscriptions, suspend or activate subscriptions, and list consumers and subscriptions.
Recurring URLS
Medium | URL |
CGI |
This URL is accessible via a post.
Recurring Request Parameters
Below is a list of all parameters that could be used and what function they are associated with. Consult the individual function information to see if it is required.
Element Name | Type | Max. Chars. | Functionals | Notes |
ActiveOnly | Boolean | 6 | ListSubscription | ”True” or “False” |
Address1 | String | 64 | Consumer, Subscription.Consumer |
|
Address2 | String | 64 | Consumer, Subscription.Consumer |
|
AmountInc | Decimal | 10 | Subscription | “110.15”, no commas or dollar symbol; decimal place may be omitted where the value is a whole dollar amount. |
AmountPaid | Decimal | 10 | Subscription | “110.15”, no commas or dollar symbol; decimal place may be omitted where the value is a whole dollar amount. |
AmountTotal | Decimal | 10 | Subscription | “110.15”, no commas or dollar symbol; decimal place may be omitted where the value is a whole dollar amount. |
BankAccountNo | String | 20 | Consumer, Subscription.Consumer |
|
BankRoutingNumber | Int32 | 9 | Consumer, Subscription.Consumer |
|
BirthDate | Date | 10 | Consumer, Subscription.Consumer | In the format "M/D/YYYY". |
City | String | 64 | Consumer, |
|
ConsumerId | Guid | 36 | Subscription, | In format “12345678-90AB-CDEF-1234-567890ABCDEF |
Country | String | 64 | Consumer, |
|
DLN | String | 32 | Consumer, |
|
DLS | String | 2 | Consumer, |
|
String | 64 | Consumer, |
| |
EndCode | String | 64 | Subscription |
|
EndTime | Date | 10 | Subscription | In the format "M/D/YYYY". |
Group | String | 64 | Subscription, |
|
Id | Guid | 36 | Consumer, | format “12345678-90AB-CDEF-1234-567890ABCDEF” |
IsLive | Boolean | 6 | Subscription |
|
Name | String | 64 | Consumer, |
|
Network | String | 3 | Subscription |
|
Notes | String | 256 | Consumer, |
|
Phone | String | 20 | Consumer |
|
RequestIdentifier | String | 512 | Consumer, |
|
SchCode | String | 64 | Subscription |
|
SECCode | String | 3 | Consumer, |
|
SSN | Int32 | 9 | Consumer, |
|
StartTime | Date | 10 | Subscription | In the format "M/D/YYYY". |
State | String | 2 | Consumer, |
|
Status | String | 1 | Subscription, |
|
SubcriptionId | Guid | 36 | SubscriptionActivation | format “12345678-90AB-CDEF-1234-567890ABCDEF” |
Zip | String | 10 | Consumer, |
|
CREDENTIALS AND VERSIONING
You will need to input your credentials that you received from Check Commerce in your welcome email.
Element Name | Type | Max. Chars. | Requirements | Notes |
UserID | String | 16 | Required | Normally this is the merchant's 6-digit Company Number. |
Password | String | 16 | Required |
|
Version | String | 15 | Optional |
|
The current version of this API is 1.4. If you put in no version information then the newest version is assumed. It is highly recommended that you input this parameter.
RECURRING RESPONSE PARAMETERS
All responses contain the following four parameters
Element Name | Required. | Description |
Success | True | Either Success or Error |
RequestIdentifier | False | This function’s specific user supplied identifier |
ResponseCode | True | 0 Unknown |
ErrorMessage | False | This will only contain information when there is an error |
FUNCTIONS
CONSUMER
The consumer function allows you to either update or insert a consumer record. A consumer record contains all the information needed for a transaction. This includes the consumer’s personal information and their banking information.
PARAMETER INFORMATION
Element Name | Required. | Description |
Id | False 1 | Id of Consumer |
RequestIdentifier | False 2 | This function’s specific user supplied identifier |
Name | True | Name of Consumer |
BankAccountNo | True | BankAccount Number for the Consumer’s bank account |
BankRoutingNumber | True | ABA or Routing Number of the Consumer’s bank |
IsSavingsAccount | False | The default is “False”, most accounts are Checking Accounts |
Address1 | False | Address of Consumer |
Address2 | False | Address of Consumer |
City | False | City of Consumer |
State | False | State of Consumer |
Zip | False | Zip Code of Consumer |
Country | False | Country of Consumer. Although you may enter a non-US address, the bank account must be for a US bank |
DLN | False | Driver’s License Number |
DLS | False | Driver’s License State |
Phone | False | Phone of Consumer |
False | Contact Email of Consumer | |
Birthday | False | Birthday of Consumer |
SSN | False | Social Security Number |
SECCode | False 3 | The SEC Code identifies the type of transaction. Common SECCodes are: CCD Business Transaction PPD Personal Transaction TEL Telephone Authorized Transaction WEB Web Authorized Transaction |
Notes:
1 The Id is used to indicate whether a record is being updated or inserted. When the Id is present, then the record is being updated. When it is absent, then it is being inserted.
2 The RequestIdentifier is not required and not validated; whatever you pass in will be passed back to you.
3 The SECCode is validated against the SEC Codes that have been allowed for your account. If you do not input this value then your default SEC code will be used.
EXAMPLE REQUEST
Below is a minimal example:
<RecurringRequest> <Credential> <UserID>{Merchant Login Id}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> <Consumer> <Name>Ted Tester</Name> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNo>333333</BankAccountNo> </Consumer> </RecurringRequest>
This is an example with all the information filled out:
<RecurringRequest> <Credential> <UserID>{Merchant Login}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> <Consumer> <RequestIdentifier>15-ABC</RequestIdentifier> <Name>Ted Tester</Name> <Address1>123 W Tester Lane</Address1> <Address2>100</Address2> <City>Tempe</City> <State>Az</State> <Zip>85033</Zip> <Country>US</Country> <Phone>123-456-7890</Phone> <Email>Test@CheckCommerce.com</Email> <BirthDate>03/20/1976</BirthDate> <SSN>100-10-1001</SSN> <DLN>D01100111</DLN> <DLS>AZ</DLS> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNo>123098</BankAccountNo> <Notes>Test Consumer for Integration</Notes> <SECCode>WEB</SECCode> <IsSavingsAccount>False</IsSavingsAccount> </Consumer> </RecurringRequest>
RESPONSE
These are the parameters that are returned inside the RecurringResponse.Consumer XML tags.
Element Name | Description |
Success | Either the values: “Success”, “Error”, or “Unknown” |
ResponseCode | 0 is Unknown |
ErrorMessage | Either a “No error”, or the specific error message associated with a failed request |
Version | The version of the API used to enter this transaction |
Id | Id of Consumer. Always returned on success |
RequestIdentifier | This function’s specific user supplied identifier. Whatever value you pass in to this on the request you will receive in the response |
Name | Name of Consumer |
CoNo | The Company Number associated with this Consumer |
Address1 | Address of Consumer |
Address2 | Address of Consumer |
City | City of Consumer |
State | State of Consumer |
Zip | Zip Code of Consumer |
Country | Country of Consumer. Although you may enter a non-US address, the bank account must be for a US bank |
DLN | Driver’s License Number |
DLS | Driver’s License State |
Phone | Phone of Consumer |
Contact Email of Consumer | |
Birthday | Birthday of Consumer |
SSN | Social Security Number |
SECCode | The SEC Code identifies the type of transaction. Common SECCodes are: CCD Business Transaction PPD Personal Transaction TEL Telephone Authorized Transaction WEB Web Authorized Transaction |
BankRoutingNumber | ABA or Routing Number of the Consumer’s bank |
BankAccountNoMasked | Masked bank account number. The last four digits of the full number are shown |
IsSavingsAccount | False for a Checking Account, True for a Savings Account |
EXAMPLE RESPONSE
Here is an example of the Consumer XML Response.
<RecurringResponse> <Consumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage>No error</ErrorMessage> <RequestIdentifier>15-ABC</RequestIdentifier> <Id>4c2c6658-936d-4a30-99d8-35d440cb2a2b</Id> <Version>1.4</Version> <CoNo>999999</CoNo> <Name>Ted Tester</Name> <Address1>123 W Tester Lane</Address1> <Address2>100</Address2> <City>Tempe</City> <State>Az</State> <Zip>85033</Zip> <Country>US</Country> <Phone>1234567890</Phone> <Email>Test@CheckCommerce.com</Email> <SSN>100101001</SSN> <DLN>D01100111</DLN> <DLS>AZ</DLS> <SECCode>WEB</SECCode> <IsSavingsAccount>False</IsSavingsAccount> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNoMasked>xx3098</BankAccountNoMasked> <SECCode>WEB</SECCode> </Consumer> </RecurringResponse>
SUBSCRIPTION
The subscription function allows you to either update or insert a subscription record. A subscription is the combination of a schedule and a consumer. When a subscription is active it will be processed according to the schedule and create transactions as time progresses.
PARAMETER INFORMATION
Element Name | Required. | Description |
Id | False1 | Id of Subscription |
RequestIdentifier | False2 | This function’s specific user supplied identifier |
ConsumerId | False3 | Consumer record |
Status | True | Status of subscription: A for Active |
IsLive | False | Subscriptions that are not live will not be originated |
Network | True | At this point in time the only acceptable value for this parameter is “ACH” |
StartTime | True | Start Date for entering transactions |
Payments | False4 | The Number of payments to be made on this subscription. |
AmountInc | True | The amount of each transaction enter on this subscription |
AmountTotal | False4 | The amount to be paid total. The subscription will enter the Ended status once this amount has been reached |
EndCode | True | The rule to determine when the subscription will stop. Valid values are: Indefinite It will never stop |
SchCode | True | The schedule by which transactions will be entered. See below |
Group | False | A name by which to group related subscriptions |
Notes | False | A note you wish to add to the subscription information |
EndTime | False4 | Used to determine when transactions should not be entered |
Notes:
1 The Id is used to indicate whether a record is being updated or inserted. When the Id is present, then the record is being updated. When it is absent, then it is being inserted.
2 The RequestIdentifier is not required and not validated; whatever you pass in will be passed back to you.
3 The ConsumerId is required when a consumer record is not created inside the subscription.
4 This may or may not be required depending on the SchCode.
SCHCODE RULES
There are a number of schedules that a subscription can follow. Below are the types and parameters of the schedules.
Type | Description. | Format | Parmeters |
Weekly | Schedule that fires once per X weeks.3 | Weekly:{0},{1} | 0 Every X weeks |
Monthly | Schedule that fires once per month. | Monthly:{0} | 0 Day of the month |
SubYearly1 | Schedule that fires once per X months. | SubYearly:{0},{1},{2} | 0 Monthly Increment |
Yearly2 | Schedule that fires once per year. | Yearly:{0},{1} | 0 Month of Year |
1When a day greater than 28 is specified, it will be clamped to the last day of the month as needed.
2When Feb.29 is specified, it will be clamped to Feb.28 as needed.
3The date format is in yyyyMMdd, where yyyy is a four digit year, MM is a two digit month, and dd is a two digit day. June 25th 2009 would be 20090625.
Example | Meaning |
Weekly:2,20100615 | Every other Tuesday, since June 15th 2010 is a Tuesday. Starting on the StartDate parameter. |
Monthly:1 | Every 1st of the Month |
SubYearly:2,5,7 | Every Two Months from May 7th |
Yearly:7,1 | Every Year on July 1st |
EXAMPLE REQUEST
<RecurringRequest> <Subscription> <RequestIdentifier>000101</RequestIdentifier> <Consumer> <Name>Ted Tester</Name> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNo>445566</BankAccountNo> </Consumer> <Status>A</Status> <IsLive>true</IsLive> <Network>ACH</Network> <StartTime>6/5/2012</StartTime> <AmountInc>100</AmountInc> <EndCode>Indefinite</EndCode> <SchCode>Weekly:2,20100615</SchCode> <Group>Ted Tester</Group> </Subscription> <Credential> <UserID>{Merchant Login}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> </RecurringRequest>
RESPONSE
These are the parameters that are returned inside the RecurringResponse.Subscription XML tags.
Element Name | Description |
Success | Either the values: “Success”, “Error”, or “Unknown” |
ResponseCode | 0 is Unknown |
ErrorMessage | Either a “No error”, or the specific error message associated with a failed request |
Version | The version of the API used to enter this transaction |
Id | Id of Subscription. Always returned on success |
RequestIdentifier | This function’s specific user supplied identifier. Whatever value you pass in to this on the request you will receive in the response |
Consumer | A full consumer object is returned |
CoNo | Associated company number |
Group | A logical organizing name. Many subscriptions can be in one group |
AmountInc | The amount that each individual transaction created for this subscription will be for |
AmountPaid | The total of the transactions’ amount submitted from this subscription |
AmountTotal | The total amount to be paid before this subscription is completed |
EndCode | The end condition of this subscription. See above |
EndDesc | The description of the end condition |
EndTime | The date that this subscription will become Ended, if the end code specifies this parameter will be used |
IsLive | When false, this subscription creates transactions that will not originate. True for a normal subscription that does create normal transactions |
IsTest | When IsLive is true, this is false. When IsLive is false, this is true |
Network | Always ACH |
NextTime | The next time this subscription will generate a transaction |
Notes | The notes associated with this subscription |
Payments | Either zero when it isn’t used, or the number of transactions to create before this subscription reaches the Ended status |
PrevTime | The last time this subscription created a transaction |
PrevTranID | The last transaction’s ID that was created for this subscription |
StartTime | The date at which this subscription starts running |
Status | Either Active, Suspended, or Ended. Ended is the normal outcome of a subscription that has completed it’s end condition |
SchCode | The coded schedule, examples above |
SchDesc | A full text description of the schedule |
UsesTime | A Boolean value indicating whether or not the schedule takes into account the time of day |
EXAMPLE RESPONSE
For the above request the following is its response:
<RecurringResponse> <Subscription> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage>No error</ErrorMessage> <RequestIdentifier>000103</RequestIdentifier> <Id>11111111-2222-3333-4444-555555555555</Id> <Version>1.4</Version> <Group>Ted Tester</Group> <AmountInc>100.00</AmountInc> <AmountPaid>0.00</AmountPaid> <AmountTotal>0.00</AmountTotal> <CoNo>999999</CoNo> <EndCode>Indefinite</EndCode> <EndDesc>Indefinitely</EndDesc> <EndTime /> <IsLive>True</IsLive> <IsTest>False</IsTest> <Network>ACH</Network> <NextTime>6/5/2012 12:00:00 AM</NextTime> <Notes /> <Payments>0</Payments> <PrevTime /> <PrevTranID /> <StartTime>6/5/2012 12:00:00 AM</StartTime> <Status>Active</Status> <SchCode>Weekly:2,20100615</SchCode> <SchDesc>Every other Tuesday</SchDesc> <UsesTime>False</UsesTime> <Consumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage>No error</ErrorMessage> <RequestIdentifier /> <Id>FFFFFFFF-EEEE-DDDD-CCCC-BBBBBBBBBBBB</Id> <Version /> <CoNo>999999</CoNo> <Name>Ted Tester</Name> <Address1 /> <Address2 /> <City /> <State /> <Zip /> <Country /> <Phone /> <Email /> <DLN /> <DLS /> <SECCode /> <IsSavingsAccount>False</IsSavingsAccount> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNoMasked>xx5566</BankAccountNoMasked> <SECCode /> </Consumer> </Subscription> </RecurringResponse>
SUBSCRIPTION ACTIVATION
The Subscription Activation function lets you change the status of a subscription. This is mainly used to suspend a subscription if it should no longer be needed.
PARAMETER INFORMATION
Element Name | Required. | Description |
SubscriptionId | True | Id of Subscription to change |
RequestIdentifier | False1 | This function’s specific user supplied identifier |
Status | True | Status of subscription: A for Active |
1 The RequestIdentifier is not required and not validated; whatever you pass in will be passed back to you.
REQUEST EXAMPLE
<RecurringRequest> <SubscriptionActivation> <SubscriptionId>00000000-1111-2222-3333-444444444444</SubscriptionId> <Status>S</Status> <RequestIdentifier>SA1</RequestIdentifier> </SubscriptionActivation> <Credential> <UserID>{Merchant Login}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> </RecurringRequest>
RESPONSE
The response is made up of the SubscriptionActivation, and the Subscription and Consumer information embedded within it.
RESPONSE EXAMPLE
<RecurringResponse> <SubscriptionActivation> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier>SA1</RequestIdentifier> <Version>1.4</Version> <Subscription> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier>SA1</RequestIdentifier> <Id>00000011-0022-0033-0044-000000000055</Id> <Version /> <Group>Ted Tester</Group> <AmountInc>100.00</AmountInc> <AmountPaid>0.00</AmountPaid> <AmountTotal>0.00</AmountTotal> <CoNo>999999</CoNo> <EndCode>Indefinite</EndCode> <EndDesc>Indefinitely</EndDesc> <EndTime /> <IsLive>True</IsLive> <IsTest>False</IsTest> <Network>ACH</Network> <NextTime>6/1/2012 12:00:00 AM</NextTime> <Notes /> <Payments>0</Payments> <PrevTime /> <PrevTranID /> <StartTime>6/1/2012 12:00:00 AM</StartTime> <Status>Suspended</Status> <SchCode>Weekly:2,20100615</SchCode> <SchDesc>Every other Tuesday</SchDesc> <UsesTime>False</UsesTime> <Consumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier /> <Id>00000000-0000-0000-0000-000000000000</Id> <Version /> <CoNo>999999</CoNo> <Name>Ted Tester</Name> <Address1 /> <Address2 /> <City /> <State /> <Zip /> <Country /> <Phone /> <Email /> <DLN /> <DLS /> <SECCode /> <IsSavingsAccount>False</IsSavingsAccount> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNoMasked>xx3333</BankAccountNoMasked> <SECCode /> </Consumer> </Subscription> </SubscriptionActivation> </RecurringResponse>
LIST CONSUMER
Element Name | Required. | Description |
ConsumerId | False1 | Id of Consumer |
RequestIdentifier | False2 | This function’s specific user supplied identifier |
1The ConsumerId is not required, but when it is input the search will only contain one result
2The RequestIdentifier is not required and not validated; whatever you pass in will be passed back
EXAMPLE REQUEST
<RecurringRequest> <ListConsumer> <RequestIdentifier>List01</RequestIdentifier> </ListConsumer> <Credential> <UserID>{Merchant Login}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> </RecurringRequest>
RESPONSE
The response is comprised of the ListConsumer and embedded Consumer objects.
EXAMPLE RESPONSE
<RecurringResponse> <ListConsumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier>List01</RequestIdentifier> <Version>1.4</Version> <Consumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier>List01</RequestIdentifier> <Id>00000000-0000-0000-0000-000000000000</Id> <Version /> <CoNo>999999</CoNo> <Name>Joe TEST</Name> <Address1>1313 Elm Street</Address1> <Address2 /> <City>Scottsdale</City> <State>AZ</State> <Zip>85254</Zip> <Country /> <Phone>5555555555</Phone> <Email>Test@Test.com</Email> <Birthday>1/1/1970 12:00:00 AM</Birthday> <SSN>123456789</SSN> <DLN>123456789</DLN> <DLS>TX</DLS> <SECCode>PPD</SECCode> <IsSavingsAccount>False</IsSavingsAccount> <BankRoutingNumber>122187238</BankRoutingNumber> <BankAccountNoMasked>xxxx5678</BankAccountNoMasked> <SECCode>PPD</SECCode> </Consumer> </ListConsumer> </RecurringResponse>
LIST SUBSCRIPTION
The ListSubscription function returns a list of subscriptions for a merchant.
PARAMETER INFORMATION
Element Name | Required | Description |
ConsumerId | False | When present this will return all subscriptions linked to this consumer |
RequestIdentifier | False1 | This function’s specific user supplied identifier |
Group | False | The group to filter on |
ActiveOnly | False | When false this will return Suspended, Active, and Ended subscriptions. When true this will return only Active subscriptions |
1 The RequestIdentifier is not required and not validated; whatever you pass in will be passed back
EXAMPLE REQUEST
<RecurringRequest> <ListSubscription> <Group>Ted Tester</Group> </ListSubscription> <Credential> <UserID>{Merchant Login}</UserID> <Password>{Merchant Password}</Password> <Version>1.4</Version> </Credential> </RecurringRequest>
RESPONSE
The response is the ListSubscription, with embedded subscription and consumer information.
EXAMPLE RESPONSE
<RecurringResponse> <ListSubscription> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier /> <Version>1.4</Version> <Subscription> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier /> <Id>00000000-0000-0000-0000-000000000000</Id> <Version /> <Group>Ted Tester</Group> <AmountInc>100.00</AmountInc> <AmountPaid>0.00</AmountPaid> <AmountTotal>0.00</AmountTotal> <CoNo>999999</CoNo> <EndCode>Indefinite</EndCode> <EndDesc>Indefinitely</EndDesc> <EndTime /> <IsLive>True</IsLive> <IsTest>False</IsTest> <Network>ACH</Network> <NextTime>6/1/2012 12:00:00 AM</NextTime> <Notes /> <Payments>0</Payments> <PrevTime /> <PrevTranID /> <StartTime>6/1/2012 12:00:00 AM</StartTime> <Status>Active</Status> <SchCode>Weekly:2,20100615</SchCode> <SchDesc>Every other Tuesday</SchDesc> <UsesTime>False</UsesTime> <Consumer> <Success>Success</Success> <ResponseCode>1</ResponseCode> <ErrorMessage /> <RequestIdentifier /> <Id>00000000-0000-0000-0000-000000000000</Id> <Version /> <CoNo>999999</CoNo> <Name>Ted Tester</Name> <Address1 /> <Address2 /> <City /> <State /> <Zip /> <Country /> <Phone /> <Email /> <DLN /> <DLS /> <SECCode /> <IsSavingsAccount>False</IsSavingsAccount> <BankRoutingNumber>123456780</BankRoutingNumber> <BankAccountNoMasked>xx3333</BankAccountNoMasked> <SECCode /> </Consumer> </Subscription> </ListSubscription> </RecurringResponse>