Recurring API

Overview 
The Cardknox Recurring API, designed in the RESTful architectural style, lets you process recurring transactions through the Cardknox gateway based on customized schedules. You can create recurring schedules along with customers and payment methods. Additionally, you can process single transactions for a customer and change a merchant's settings for recurring schedule reports.
Authorization
All requests require passing in an Authorization header. The value of the Authorization header should be your gateway API key. Contact Cardknox at [email protected], and we will send you an API key via email.
Versioning
Recurring API V2 is versioned to allow stability for integrators and flexibility for Cardknox to continue making improvements.
Major Version
The URL contains the major version number parameter. This version number would only be changed if there is a major change that overhauls the entire API.
Example: https://api.cardknox.com/v2​
Minor Version
This version number is incremented when a breaking change to the existing API is implemented (for example, a change to how requests are processed or how responses are sent back). 
The minor version is passed in the X-Recurring-Api-Version header: X-Recurring-Api-Version = 2.1
Request Method
Method: ​
The Cardknox gateway requires the POST method to be used for enhanced security.
We do not support the GET method.
Base URL
The base URL for all requests is https://api.cardknox.com/v2​
Customer Endpoints
/CreateCustomer
Add a new customer record, which can then be linked to payment methods and schedules.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerNumber
No
string
Merchant's internal customer identifier.
CustomerNotes
No
string
Notes pertaining to the customer.
Email
No
string
Customer's email address.
Fax
No
string
Customer's fax number.
BillFirstName
Yes*
string
Customer's first name for their billing profile.
*Required if BillLastName and BillCompany are not passed in.
BillMiddleName
No
string
Customer's middle name or middle initial for their billing profile.
BillLastName
Yes*
string
Customer's last name or family name for their billing profile.
*Required if BillFirstName and BillCompany are not passed in.
BillCompany
Yes*
string
Customer's company name for their billing profile.
*Required if BillFirstName and BillLastName are not passed in.
BillStreet
No
string
Customer's street address for their billing profile.
BillStreet2
No
string
Customer's street address second line for their billing profile.
BillCity
No
string
Customer's city for their billing profile.
BillState
No
string
Customer's state for their billing profile.
BillZip
No
string
Customer's ZIP code or postal code for their billing profile.
BillCountry
No
string
Customer's country for their billing profile.
BillPhone
No
string
Customer's phone number for their billing profile.
BillMobile
No
string
Customer's mobile number for their billing profile.
ShipFirstName
No
string
Customer’s first name for their shipping profile.
ShipMiddleName
No
string
Customer’s middle name or initial for their shipping profile.
ShipLastName
No
string
Customer’s last/family name for their shipping profile.
ShipCompany
No
string
Customer’s company name for their shipping profile.
ShipStreet
No
string
Customer’s street address for their shipping profile.
ShipStreet2
No
string
Customer’s street address second line for their shipping profile.
ShipCity
No
string
Customer’s city for their shipping profile.
ShipState
No
string
Customer’s state for their shipping profile.
ShipZip
No
string
Customer’s ZIP code for their shipping profile.
ShipCountry
No
string
Customer’s country for their shipping profile.
ShipPhone
No
string
Customer’s phone number for their shipping profile.
ShipMobile
No
string
Customer’s mobile number for their shipping profile.
ShipEmail
No
string
Customer’s shipping email address for their shipping profile.
CustomerCustomXX
No
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerNumber" : "123456",
    "CustomerNotes" : "Vip Customer",
    "Email" : "[email protected]",
    "Fax" : "",
    "BillFirstName" : "John",
    "BillMiddleName" : "G",
    "BillLastName" : "Doe",
    "BillCompany" : "ACME Inc.",
    "BillStreet" : "123 Main Street",
    "BillStreet2" : "STE 1",
    "BillCity" : "AnyTown",
    "BillState" : "NY",
    "BillCountry" : "USA",
    "BillZip" : "11218",
    "BillPhone" : "",
    "BillMobile" : "",
    "ShipFirstName" : "John",
    "ShipMiddleName" : "G",
    "ShipLastName" : "Doe",
    "ShipCompany" : "ACME Inc.",
    "ShipStreet" : "123 Main Street",
    "ShipStreet2" : "STE 1",
    "ShipCity" : "AnyTown",
    "ShipState" : "NY",
    "ShipCountry" : "USA",
    "ShipZip" : "11218",
    "ShipPhone" : "",
    "ShipMobile" : "",
    "ShipEmail" : "[email protected]",
    "CustomerCustom01" : "MyCustomValue",
    "CustomerCustom02" : "MyCustomValue2",
    "CustomerCustom03" : "MyCustomValue3"
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
CustomerId
integer
The created customer ID.
​
Sample Response
{ "RefNum": "r1234567890", "Result": "S", "Error": "", "CustomerId": "c1234567890" }
/UpdateCustomer
Update existing customer information.
Note: All fields with values must be passed in (even fields that are not being updated). Any fields not passed in are treated as being set to blank.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
Revision
Yes
integer
The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
CustomerId
Yes
string
The ID of the customer to update.
CustomerNumber
No
string
Merchant's internal customer identifier.
CustomerNotes
No
string
Notes pertaining to the customer.
Email
No
string
Customer's email address.
Fax
No
string
Customer's fax number.
BillFirstName
Yes*
string
Customer's first name for their billing profile.
*Required if BillLastName and BillCompany are not passed in.
BillMiddleName
No
string
Customer's middle name or middle initial for their billing profile.
BillLastName
Yes*
string
Customer's last name or family name for their billing profile.
*Required if BillFirstName and BillCompany are not passed in.
BillCompany
Yes*
string
Customer's company name for their billing profile.
*Required if BillFirstName and BillLastName are not passed in.
BillStreet
No
string
Customer's street address for their billing profile.
BillStreet2
No
string
Customer's street address second line for their billing profile.
BillCity
No
string
Customer's city for their billing profile.
BillState
No
string
Customer's state for their billing profile.
BillZip
No
string
Customer's ZIP code or postal code for their billing profile.
BillCountry
No
string
Customer's country for their billing profile.
BillPhone
No
string
Customer's phone number for their billing profile.
BillMobile
No
string
Customer's mobile number for their billing profile.
ShipFirstName
No
string
Customer’s first name for their shipping profile.
ShipMiddleName
No
string
Customer’s middle name or initial for their shipping profile.
ShipLastName
No
string
Customer’s last/family name for their shipping profile.
ShipCompany
No
string
Customer’s company name for their shipping profile.
ShipStreet
No
string
Customer’s street address for their shipping profile.
ShipStreet2
No
string
Customer’s street address second line for their shipping profile.
ShipCity
No
string
Customer’s city for their shipping profile.
ShipState
No
string
Customer’s state for their shipping profile.
ShipZip
No
string
Customer’s ZIP code for their shipping profile.
ShipCountry
No
string
Customer’s country for their shipping profile.
ShipPhone
No
string
Customer’s phone number for their shipping profile.
ShipMobile
No
string
Customer’s mobile number for their shipping profile.
ShipEmail
No
string
Customer’s shipping email address for their shipping profile.
CustomerCustomXX
No
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
	"Revision" : 1,
    "CustomerId" : "c123456",
    "CustomerNumber" : "123456",
    "CustomerNotes" : "Vip Customer",
    "Email" : "[email protected]",
    "Fax" : "",
    "BillFirstName" : "John",
    "BillMiddleName" : "G",
    "BillLastName" : "Doe",
    "BillCompany" : "ACME Inc.",
    "BillStreet" : "123 Main Street",
    "BillStreet2" : "STE 1",
    "BillCity" : "AnyTown",
    "BillState" : "NY",
    "BillCountry" : "USA",
    "BillZip" : "11218",
    "BillPhone" : "",
    "BillMobile" : "",
    "ShipFirstName" : "John",
    "ShipMiddleName" : "G",
    "ShipLastName" : "Doe",
    "ShipCompany" : "ACME Inc.",
    "ShipStreet" : "123 Main Street",
    "ShipStreet2" : "STE 1",
    "ShipCity" : "AnyTown",
    "ShipState" : "NY",
    "ShipCountry" : "USA",
    "ShipZip" : "11218",
    "ShipPhone" : "",
    "ShipMobile" : "",
    "ShipEmail" : "[email protected]",
    "CustomerCustom01" : "MyCustomValue",
    "CustomerCustom02" : "MyCustomValue2",
    "CustomerCustom03" : "MyCustomValue3"
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
/GetCustomer
Retrieves the details of a specific customer.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to retrieve.
ShowDeleted
No
boolean
A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e. customers that are not deleted will not be returned).
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c1234567890",
    "ShowDelete" : false
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Revision
integer
The revision number of the customer record.
​
CreatedDate
string
The date and time the customer was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).
​
CustomerId
string
The ID of the customer to update.
​
CustomerNumber
string
Merchant's internal customer identifier.
​
CustomerNotes
string
Notes pertaining to the customer.
​
Email
string
Customer's email address.
​
Fax
string
Customer's fax number.
​
BillFirstName
string
Customer's first name for their billing profile.
​
BillMiddleName
string
Customer's middle name or middle initial for their billing profile.
​
BillLastName
string
Customer's last name or family name for their billing profile.
​
BillCompany
string
Customer's company name for their billing profile.
​
BillStreet
string
Customer's street address for their billing profile.
​
BillStreet2
string
Customer's street address second line for their billing profile.
​
BillCity
string
Customer's city for their billing profile.
​
BillState
string
Customer's state for their billing profile.
​
BillZip
string
Customer's ZIP code or postal code for their billing profile.
​
BillCountry
string
Customer's country for their billing profile.
​
BillPhone
string
Customer's phone number for their billing profile.
​
BillMobile
string
Customer's mobile number for their billing profile.
​
ShipFirstName
string
Customer’s first name for their shipping profile.
​
ShipMiddleName
string
Customer’s middle name or initial for their shipping profile.
​
ShipLastName
string
Customer’s last/family name for their shipping profile.
​
ShipCompany
string
Customer’s company name for their shipping profile.
​
ShipStreet
string
Customer’s street address for their shipping profile.
​
ShipStreet2
string
Customer’s street address second line for their shipping profile.
​
ShipCity
string
Customer’s city for their shipping profile.
​
ShipState
string
Customer’s state for their shipping profile.
​
ShipZip
string
Customer’s ZIP code for their shipping profile.
​
ShipCountry
string
Customer’s country for their shipping profile.
​
ShipPhone
string
Customer’s phone number for their shipping profile.
​
ShipMobile
string
Customer’s mobile number for their shipping profile.
​
ShipEmail
string
Customer’s shipping email address for their shipping profile.
​
CustomerCustomXX
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "CustomerId": "c123456",
    "Revision": 1,
    "CustomerNotes": "Vip Customer",
    "CustomerNumber": "123456",
    "DefaultPaymentMethodId": "",
    "CreatedDate": "2019-08-20 14:30:57.578",
    "Email": "[email protected]",
    "BillFirstName": "John",
    "BillMiddleName": "G",
    "BillLastName": "Doe",
    "BillCompany": "ACME Inc.",
    "BillStreet": "123 Main Street",
    "BillStreet2": "STE 1",
    "BillCity": "AnyTown",
    "BillState": "NY",
    "BillZip": "11218",
    "BillCountry": "USA",
    "ShipFirstName": "John",
    "ShipMiddleName": "G",
    "ShipLastName": "Doe",
    "ShipCompany": "ACME Inc.",
    "ShipStreet": "123 Main Street",
    "ShipStreet2": "STE 1",
    "ShipCity": "AnyTown",
    "ShipState": "NY",
    "ShipZip": "11218",
    "ShipCountry": "USA",
    "ShipEmail": "[email protected]",
    "CustomerCustom01": "MyCustomValue",
    "CustomerCustom02": "MyCustomValue2",
    "CustomerCustom03": "MyCustomValue3"
}
/DeleteCustomer
Deletes a customer record. You cannot delete a customer who has a recurring schedule that is active.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to update.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c123456"
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
/ListCustomers
Lists customers created by a merchant.
Request Body (JSON)
Parameter
Required
Type
Default Value
Description
Valid Values
SoftwareName
Yes
string
​
The name of the software making the request.
​
SoftwareVersion
Yes
string
​
The version of the software making the request.
​
PageSize
No
integer
100
The maximum number of items to retrieve for this request.
​
NextToken
No
string
​
A token that can be sent in to the following request to get the next set of customers.
​
SortOrder
No
string
Ascending
The list order. Order is determined by customer creation date.
Ascending, Descending
Filters
No
object
{
    "IsDeleted" : false
}
Filters that can be applied to limit the result set.
Filters will remove any items that don't contain the string for that filter value. If there are multiple filters applied the item must match all of them.
Available filters:
CustomerId
CustomerNumber
IsDeleted
Email
BillName
BillFirstName
BillLastName
BillMiddleName
BillCompany
BillStreet
BillStreet2
BillCity
BillState
BillZip
BillCountry
BillPhoneNumber
BillPhone
BillMobile
BillFax
​
Sample Request
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"BillFirstName" : "John",
		"BillState" : "NY"
	}
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Customers
object[]
An array of customer objects.
Refer to the /GetCustomer endpoint for the values that are returned for each customer.
​
NextToken
string
A token to include in the next request to get the next set of results.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
	"Customers" : [
        {
            "CustomerId" : "c123456",
            "Revision" : 1,
            "BillFirstName" : "John",
            "BillLastName" : "Doe",
            "BillState" : "NY"
        },
        {
            "CustomerId" : "c123457",
            "Revision" : 1,
            "BillFirstName" : "Johnathan",
            "BillLastName" : "Doe",
            "BillState" : "NY"
        }
    ]
}
Payment Method Endpoints
/CreatePaymentMethod
Adds a new payment method to a customer’s account profile.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to update with the new payment method.
Token
Yes
string
Cardknox token that references a previously used payment method to use for the charge.
TokenType
Yes
string
The Token payment type.
TokenAlias
No
string
Custom name for the Token.
Exp
Yes*
string
Credit card expiration date.
*Required if Token is an iFields token and TokenType is cc.
Routing
Yes*
string
ACH payment routing number.
*Required if Token is an iFields token and TokenType is ach.
Name
No
string
Name on the customer's account.
*Required for ACH (check) transactions.
Street
No
string
Customer's street address for their billing profile.
Zip
No
string
Customer's ZIP code or postal code for their billing profile.
SetAsDefault
No
boolean
Sets this payment method as the default payment method.
Note: If there are no other payment methods, this method is automatically set as the default.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c123456",
	"Token" : "pm4408q3327hq551h5h51058qh6n87mn",
	"TokenType" : "cc",
	"TokenAlias" : "",
	"Exp" : "1220",
	"Routing" : "",
	"Name" : "",
	"Street" : "",
	"Zip" : "",
	"SetAsDefault" : false
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
PaymentMethodId
string
The ID of the created payment method.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c123456_pm123456
}
/UpdatePaymentMethod
Updates an existing payment method.
Note: All fields with values must be passed in (even fields that are not being updated). Any fields not passed in are treated as being set to blank.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
Revision
Yes
integer
The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
PaymentMethodId
Yes
string
The ID of the payment method to update.
TokenAlias
No
string
Custom name for the Token.
Exp
Yes*
string
Credit card expiration date.
*Required if Token is an iFields token and TokenType is cc.
Routing
Yes*
string
ACH payment routing number.
*Required if Token is an iFields token and TokenType is ach.
Name
No*
string
Name on the customer's account.
*Required for ACH (check) transactions.
Street
No
string
Customer's street address for their billing profile.
Zip
No
string
Customer's ZIP code or postal code for their billing profile.
SetAsDefault
No
boolean
Sets this payment method as the default payment method.
Note: If there are no other payment methods, this method is automatically set as the default.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "Revision" : 1,
    "CustomerId" : "c123456",
	"TokenAlias" : "",
	"Exp" : "1220",
	"Routing" : "",
	"Name" : "",
	"Street" : "",
	"Zip" : "",
	"SetAsDefault" : false
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
/GetPaymentMethod
Retrieves an existing payment method.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
PaymentMethodId
Yes
string
The ID of the payment method to retrieve.
ShowDeleted
No
boolean
A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., payment methods that are not deleted will not be returned).
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "PaymentMethodId" : "c123456_pm123456",
	"ShowDeleted" : false
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
PaymentMethodId
string
The ID of the payment method.
​
Revision
number
The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
​
Token
string
Cardknox token that references a previously used payment method to use for the charge.
​
TokenType
string
The Token payment type.
CC, Check
TokenAlias
string
Custom name for the Token.
​
Exp
string
Credit card expiration date (in MMYY format).
​
Issuer
string
The credit card issuer.
Note: This field is only populated when TokenType is CC.
​
MaskedCardNumber
string
The masked credit card number.
Note: This field is only populated when TokenType is CC.
​
Name
string
The name on the check.
Note: This field is only populated when TokenType is Check.
​
Street
string
The building number and street name of the customer being billed.
​
Zip
string
The zip code of the customer being billed.
​
CreatedDate
string
The date and time the payment method was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c12345678_pm12345678",
    "Revision": 1,
    "Token": "qfjjf12m4iimkldfvoijv9012frljl0a",
    "TokenType": "CC",
    "TokenAlias": "",
    "Exp": "1220",
    "Issuer": "Visa",
    "MaskedCardNumber": "4xxxxxxxxxxx1111",
    "Name": "",
    "Street": "",
    "Zip": "",
    "CreatedDate": "2019-01-01 00:00:00.000"
}
/DeletePaymentMethod
Removes a payment method from the customer’s record. This will fail if the payment method is the customer's only payment method and there are active schedules.
Request Body (JSON)
Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
PaymentMethodId
Yes
string
The ID of the payment method to retrieve.
Sample Request
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "PaymentMethodId" : "c123456_pm123456"
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
/ListPaymentMethods
Return payment methods based on specific search parameters.
Request Body (JSON)
Parameter
Required
Type
Default Value
Description
Valid Values
SoftwareName
Yes
string
​
The name of the software making the request.
​
SoftwareVersion
Yes
string
​
The version of the software making the request.
​
PageSize
No
integer
100
The maximum number of items to retrieve for this request.
​
NextToken
No
string
​
A token that can be sent in to the following request to get the next set of payment methods.
​
SortOrder
No
string
Ascending
The list order. Order is determined by payment method creation date.
Ascending, Descending
Filters
No
object
{
    "IsDeleted" : false
}
Filters that can be applied to limit the result set.
Filters will remove any items that don't contain the string for that filter value. If there are multiple filters applied, the item must match all of them.
Available filters:
IsDeleted
CustomerId
PaymentMethodId
Token
TokenType
TokenAlias
​
Sample Request
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"NextToken" : "",
	"PageSize" : 500,
	"Filters" : {
		"IsDeleted" : false
	}
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
PaymentMethods
object[]
An array of payment method objects.
Refer to the /GetPaymentMethod endpoint for the values that are returned for each payment method.
​
NextToken
string
A token to include in the next request to get the next set of results.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
  	"PaymentMethods": [
    	{
      		"PaymentMethodId": "c123456_pm123456",
      		"Token": "ervb24g45fcr2gsdbsgbwxbtrgxt314",
 		    "TokenType": "check",
		    "Street": "123",
		    "Zip": "08701",
		    "CreatedDate": "0001-01-01 12:00:AM",
		    "Revision": 1
	    },
    	{
    		"PaymentMethodId": "c123456_pm123457",
		    "Token": "mpq93n8519hq6pm29312m1n7mm3n7204",
		    "TokenType": "card",
		    "CreatedDate": "0001-01-01 12:00:AM",
		    "Revision": 1
    	}
    ]
}
Schedule Endpoints
/CreateSchedule
Create a recurring payment schedule. Schedules have two main parameters: IntervalType and IntervalCount. You can set IntervalType to day, week, month, or year. The IntervalCount parameter determines the number of times the IntervalType should pass before the next payment schedule is triggered.
Example 1: To process a charge every two weeks, set IntervalType to week and set IntervalCount to 2. This specifies that two weeks should pass before initiating a new charge.
Example 2: To process a charge every 10 days, set IntervalType to day and set IntervalCount to 10. This specifies that 10 days should pass before initiating a new charge.
Unsuccessful Payments: If an attempted payment is unsuccessful (i.e., the card is declined), the system reschedules the charge for the following day. This can be done up to five times, provided that the rescheduled payment doesn’t overlap into the next payment cycle. After five unsuccessful attempts, or if rescheduling the payment as above will overlap into the next payment cycle, this individual payment will be canceled, but the entire schedule remains in effect.
Request Body (JSON)
Parameter
Required
Type
Default Value
Description
Valid Values
SoftwareName
Yes
string
​
The name of the software making the request.
​
SoftwareVersion
Yes
string
​
The version of the software making the request.
​
CustomerId
Yes*
string
​
Customer's unique ID number.
*Required if linking the schedule to an existing customer.
​
NewCustomer
Yes*
object
​
The customer details. Refer to the /CreateCustomer endpoint for fields that can be set for this object.
*Required if not linking the schedule to an existing customer. This cannot be set if linking to an existing customer.

​
NewPaymentMethod
Yes*
object
​
The payment method details. Refer to the /CreatePaymentMethod endpoint for fields that can be set for this object.
*Required if not linking the schedule to an existing customer. This cannot be set if linking to an existing customer.
​
IntervalType
Yes
string
​
Type of time interval.
day, week, month, year
Amount
Yes
decimal
​
Total amount of each transaction.
Must be a number with up to 2 decimal places
Currency
No
string
​
Currency code to be used when processing transactions
Note: If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.
​
TotalPayments
No
integer
infinite
Total count of scheduled payment occurrences, including the initial payment.
Note: If left blank, the count is indefinite. This field cannot be set together with EndDate.
​
Cvv
No
string
​
The CVV value for the first transaction that is run if a transaction is run immediately. This value will not be applied to future transaction run by the created schedule.
​
Description
No
string
​
Additional data sent with the transaction.
​
Invoice
No
string
​
Customer's invoice number for the transaction. 
Use Invoice when available for improved duplicate handling (recommended).
​
PONumber
No
string
​
Customer's purchase order number for the transaction.
​
ScheduleName
No
string
​
Merchant's internal schedule identifier.
​
IntervalCount
No
integer
1
Number of time periods to elapse before the payment schedule is re-triggered. 
Examples:
For every 28 days, set IntervalType to day and set IntervalCount to 28.
For every other month, set IntervalType to month and set IntervalCount to 2.
​
FailedTransactionRetryTimes
No
integer
5
Maximum number of times to try before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day.
​
DaysBetweenRetriesnew
No
integer
1
Number of days between retries after a declined transaction.
Any natural number greater than 0.
SkipSaturdayAndHolidays
No
boolean
false
Indicates whether to process payments on the Sabbath and Jewish holidays.
​
CustReceipt
No
boolean
false
A flag that can be set to send the receipts to the email set in Email for the customer.
​
CalendarCulture
No
string
Gregorian
Type of calendar to use when executing month and year interval types.
Gregorian, Hebrew
UseDefaultPaymentMethodOnly
No
boolean
false
Indicates that the system should not try another card if the default card fails.
​
ScheduleRule
No
object
​
The schedule rule used to determine the next run time after each processed payment.
See Appendix A for more information on the ScheduleRule object.
​
StartDate
No
string
current date
Schedule start date in YYYY-MM-DD format. The start date must be within one year.
Unless the StartDate parameter is included to specify a future start date for the schedule, the first charge takes place immediately by default.
​
EndDate
No
string
​
Schedule expiration date in YYYY-MM-DD format.
Note: This field cannot be set together with TotalPayments.
​
AfterMaxRetriesAction
No
string
ContinueNextInterval
What action to perform after a schedule hits the maximum number of failed attempts in a single interval.
Disable: Disables the schedule.
ContinueNextInterval: Skips the current interval and continues at the next interval.
Disable, ContinueNextInterval
AllowInitialTransactionToDecline
No
boolean
false
Create the schedule even if the initial payment fails.
Note: Can be used only if the StartDate is set to today's date (or left empty).
​
CustomXX
No
string
​
Custom fields (19 available) used for custom data, such as customer comments and so forth.
Custom01 is reserved. Use Custom02 - Custom20.
​
Sample Request
{
	"SoftwareName" : "ACME Inc.", 
	"SoftwareVersion" : "1.0",
	"CustomerId" : "c123456",
	"Amount" : "1.23",
	"IntervalType" : "month",
	"IntervalCount" : 1,
	"ScheduleName" : "Sample Schedule",
	"TotalPayments" : 5,
	"SkipSaturdayAndHolidays" : false,
	"AllowInitialTransactionToDecline" : false,
	"CustReceipt" : false,
	"Custom01" : "customValue1",
	"Custom02" : "customValue2",
	"Custom03" : "customValue3"
}
Response Body (JSON)
Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
ScheduleId
string
The ID of the schedule that was created.
​
CustomerId
string
The ID of the customer that was created, if the schedule was not linked to an existing customer.
​
PaymentMethodId
string
The ID of the payment method that was created, if the schedule was not linked to an existing customer.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "ScheduleId" : "c123456_s123456"
}
/UpdateSchedule
This command lets you update some details of a schedule. You can only update information that does not change the actual schedule. For example, the CustomerId field cannot be updated (and is not listed in the parameter table below). Also, you cannot update inactive schedules.
The following fields can be updated at any point:
AfterMaxRetriesAction
Amount
CustomXX
CustReceipt
DaysBetweenRetries
Description
Invoice
PONumber
RetryAmount
ScheduleName
SkipSaturdayAndHolidays
UseDefaultPaymentMethodOnly
Any fields that are not set will use the default values (or be removed, if no default is indicated).
Request Body (JSON)
Parameter
Required
Type
Default Value
Description
Valid Values
SoftwareName
Yes
string
​
The name of the software making the request.
​
SoftwareVersion
Yes
string
​
The version of the software making the request.
​
Revision
Yes
integer
​
The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
​
ScheduleId
Yes
string
​
The ID of the schedule to update.
​
Amount
No
decimal
​
Transaction amount
​
Currency
No
string
​
Currency code to be used when processing transactions
Note: If the currency code used is not supported for the merchant and it does not run a transaction on schedule creation, the schedule will not error until the first transaction is processed.
​
TotalPayments
No
integer
infinite
Total count of scheduled payment occurrences, including the initial payment.
You can only change this field before a schedule has been completed. Additionally, you cannot set the value lower than the number of payments already processed.
Note: It can be updated to at least the number of payments processed or higher.
​
Description
No
string
​
Additional data sent with the transaction.
​
Invoice
No
string
​
Customer's invoice number for the transaction 
Use Invoice when available for improved duplicate handling (recommended).
​
PONumber
No
string
​
Customer's purchase order number for the transaction.
​
ScheduleName
No
string
​
Merchant's internal schedule identifier.
​
FailedTransactionRetryTimes
No
integer
5
Maximum number of times to try before rescheduling to the next run time if the transaction fails. Retries are run on each subsequent day.
You can only change this field before a schedule has been completed.
​
DaysBetweenRetries
No
integer
​
Number of days between retries after a declined transaction.
Any natural number greater than 0
SkipSaturdayAndHolidays
No
boolean
false
Indicates whether to process payments on the Sabbath and Jewish holidays.
​
CustReceipt
No
boolean
false
A flag that can be set to send the receipts to the email set in Email for the customer.
​
CalendarCulture
Yes
string
Gregorian
Type of calendar to use when executing month and year interval types.
Note: You cannot change this once the schedule has begun.
Gregorian, Hebrew
UseDefaultPaymentMethodOnly
No
boolean
false
Indicates that the system should not try another card if the default card fails.
​
ScheduleRule
No
object
​
Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerNumber	No	string	Merchant's internal customer identifier.
CustomerNotes	No	string	Notes pertaining to the customer.
Email	No	string	Customer's email address.
Fax	No	string	Customer's fax number.
BillFirstName	Yes*	string	Customer's first name for their billing profile. *Required if `BillLastName` and `BillCompany` are not passed in.
BillMiddleName	No	string	Customer's middle name or middle initial for their billing profile.
BillLastName	Yes*	string	Customer's last name or family name for their billing profile. *Required if `BillFirstName` and `BillCompany` are not passed in.
BillCompany	Yes*	string	Customer's company name for their billing profile. *Required if `BillFirstName` and `BillLastName` are not passed in.
BillStreet	No	string	Customer's street address for their billing profile.
BillStreet2	No	string	Customer's street address second line for their billing profile.
BillCity	No	string	Customer's city for their billing profile.
BillState	No	string	Customer's state for their billing profile.
BillZip	No	string	Customer's ZIP code or postal code for their billing profile.
BillCountry	No	string	Customer's country for their billing profile.
BillPhone	No	string	Customer's phone number for their billing profile.
BillMobile	No	string	Customer's mobile number for their billing profile.
ShipFirstName	No	string	Customer’s first name for their shipping profile.
ShipMiddleName	No	string	Customer’s middle name or initial for their shipping profile.
ShipLastName	No	string	Customer’s last/family name for their shipping profile.
ShipCompany	No	string	Customer’s company name for their shipping profile.
ShipStreet	No	string	Customer’s street address for their shipping profile.
ShipStreet2	No	string	Customer’s street address second line for their shipping profile.
ShipCity	No	string	Customer’s city for their shipping profile.
ShipState	No	string	Customer’s state for their shipping profile.
ShipZip	No	string	Customer’s ZIP code for their shipping profile.
ShipCountry	No	string	Customer’s country for their shipping profile.
ShipPhone	No	string	Customer’s phone number for their shipping profile.
ShipMobile	No	string	Customer’s mobile number for their shipping profile.
ShipEmail	No	string	Customer’s shipping email address for their shipping profile.
CustomerCustomXX	No	string	Custom fields (20 available) used for custom data such as customer comments and so forth. Use `CustomerCustom01` through `CustomerCustom20`.