Recurring API - Version 2.0

Table of Contents

For Version 1.0 of the Recurring API documentation, click here.

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 support@cardknox.com, 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: POST

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.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "CustomerNumber" : "123456", "CustomerNotes" : "Vip Customer", "Email" : "sample@example.com", "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" : "sample@example.com", "CustomerCustom01" : "MyCustomValue", "CustomerCustom02" : "MyCustomValue2", "CustomerCustom03" : "MyCustomValue3" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 6 { "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.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "Revision" : 1, "CustomerId" : "c123456", "CustomerNumber" : "123456", "CustomerNotes" : "Vip Customer", "Email" : "sample@example.com", "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" : "sample@example.com", "CustomerCustom01" : "MyCustomValue", "CustomerCustom02" : "MyCustomValue2", "CustomerCustom03" : "MyCustomValue3" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/GetCustomer

Retrieves the details of a specific customer.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "CustomerId" : "c1234567890", "ShowDelete" : false }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "RefNum": "r1234567890", "Result": "S", "Error": "", "CustomerId": "c123456", "Revision": 1, "CustomerNotes": "Vip Customer", "CustomerNumber": "123456", "DefaultPaymentMethodId": "", "CreatedDate": "2019-08-20 14:30:57.578", "Email": "sample@example.com", "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": "sample@example.com", "CustomerCustom01": "MyCustomValue", "CustomerCustom02": "MyCustomValue2", "CustomerCustom03": "MyCustomValue3" }

/DeleteCustomer

Deletes a customer record. You cannot delete a customer who has a recurring schedule that is active.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "CustomerId" : "c123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/ListCustomers

Lists customers created by a merchant.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "NextToken" : "", "PageSize" : 500, "Filters" : { "BillFirstName" : "John", "BillState" : "NY" } }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "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.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "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

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

1 2 3 4 5 6 { "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.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 7 8 9 10 11 12 13 { "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

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/GetPaymentMethod

Retrieves an existing payment method.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 6 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "PaymentMethodId" : "c123456_pm123456", "ShowDeleted" : false }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "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.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "PaymentMethodId" : "c123456_pm123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/ListPaymentMethods

Return payment methods based on specific search parameters.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "NextToken" : "", "PageSize" : 500, "Filters" : { "IsDeleted" : false } }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "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.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "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

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

1 2 3 4 5 6 { "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).

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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



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

Yes

string



Schedule start date in YYYY-MM-DD format. The start date must be within one year.

Note: This cannot be changed once the schedule has begun.



EndDate

No

string



Schedule expiration date in YYYY-MM-DD format.

Note: This field cannot be set together with TotalPayments. This cannot be changed once the schedule has completed.



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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456", "Amount" : "1.23", "ScheduleName" : "Sample Schedule", "TotalPayments" : 5, "SkipSaturdayAndHolidays" : false, "CustReceipts" : false, "Custom01" : "customValue1", "Custom02" : "customValue2", "Custom03" : "customValue3" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/EnableSchedule

Restart a schedule that was previously disabled.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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.

ScheduleId

Yes

string

The ID of the schedule to enable.

Sample Request

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/DisableSchedule

Stop, pause, cancel, or inactivate an active schedule.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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.

ScheduleId

Yes

string

The ID of the schedule to disable.

Sample Request

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/DeleteSchedule

Removes a schedule. You can only delete a schedule that is not active.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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.

ScheduleId

Yes

string

The ID of the schedule to delete.

Sample Request

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/GetSchedule

Retrieves the details for a schedule.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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.

ScheduleId

Yes

string

The ID of the schedule 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. schedules that are not deleted will not be returned).

Sample Request

1 2 3 4 5 6 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456", "ShowDeleted" : false }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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 record to update. If this does not match the current revision number of the record the update will fail.



ScheduleId

string

Schedule reference number.



ScheduleName

string

Schedule name.



CustomerId

string

Customer's unique ID number.



IsDeleted

boolean

A  flag indicating whether the record is deleted.



UseDefaultCardOnly

boolean

Indicates that the system should not try another card if the default card fails.



FailedTransactionRetryTimes

integer

Maximum number of times to try before rescheduling to the next run time if the transaction fails. The tries are spaced out into 1-day intervals.



FailedAttemptsInCurrentInterval

integer

The number of unsuccessful transactions that were processed for the current interval. This value will reset to 0 at the start of the next interval.

 

DaysBetweenRetries

integer

Number of days between retries after a declined transaction.



ScheduleRule

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

string

Schedule start date in YYYY-MM-DD format.



EndDate

string

Schedule end date in YYYY-MM-DD format.



AllowInitialTransactionToDecline

boolean

Indicates whether the schedule was setup to allow the first transaction to be declined.



Description

string

Additional data sent with the transaction (optional).



Amount

decimal

Transaction amount.



Currency

string

Currency code to be used when processing transactions

 

TotalPayments

integer

Total count of scheduled payment occurrences, including the initial payment.



PaymentsProcessed

integer

The number of payments processed by the schedule.



SkipSaturdayAndHolidays

boolean

Indicates whether to process payments on the Sabbath and Jewish holidays.



IntervalType

string

Type of time interval.



IntervalCount

integer

Number of time periods to elapse before the payment schedule is re-triggered. 

Note: Refer to the /CreateSchedule endpoint for more details.



LastTransactionStatus

string

The status of the last transaction run by the schedule.



LastTransactionError

string

The error message of the last transaction if the status was Error.



LastProjectedPaymentDate

string

The projected payment date of the last transaction that the schedule will run.

Note: This may not be 100% accurate if that last date falls on a Saturday or Holiday and SkipSaturdayAndHolidays is set.



Invoice

string

Customer's invoice number for the transaction.



PONumber

string

Customer's purchase order number for the transaction.



CustReceipt

boolean

A flag indicating whether receipts will be sent to the email set in Email for the customer.



NextScheduledRunTime

string

The date and time that the schedule will next run.



InitialRunTime

string

The date and time of the first transaction run by the schedule.



LastRunTime

string

The date and time of the last transaction run by the schedule.



IsActive

boolean

A flag indicating whether the schedule is currently enabled/active.



CalendarCulture

string

Type of calendar to use when executing month and year interval types.



CreatedDate

string

Date the schedule was created.



CustomerNumber

string

Merchant's internal customer identifier.



Email

string

Customer's email address.



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 for their billing profile.



AfterMaxRetriesAction

string

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

CustomXX

string

Custom fields (19 available) used for custom data, such as customer comments and so forth.

Custom01 is reserved.



Sample Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 { "RefNum" : "r1234567890", "Result" : "S", "Error" : "", "Revision" : 1, "ScheduleId" : "c123456_s123456", "ScheduleName" : "Sample Schedule", "CustomerId" : "c123456", "IsDeleted" : false, "UseDefaultCardOnly" : false, "FailedTransactionRetryTimes": 5, "DaysBetweenRetries" : 2, "IntervalType" : "month", "IntervalCount" : 12 "ScheduleRule" : { "RuleType" : "Nth", "N" : 1, "NthOfType" : "Weekday" } "StartDate" : "2020-04-27", "EndDate" : "2021-04-27", "AllowInitialTransactionToDecline" : false, "Description" : "Sample Schedule", "Amount" : 1.23, "TotalPayments" : 12, "PaymentsProcessed" : 2, "SkipSaturdayAndHolidays" : false, "LastTransactionStatus" : "Approved", "LastTransactionError" : "" "LastProjectedPaymentDate" : "2021-04-27", "Invoice" : "1234567", "PONumber" : "1234567", "CustReceipts" : false, "NextScheduledRunTime" : "2020-06-27", "InitialRunTime" : "2020-04-27 01:03:50", "LastRunTime" : "2020-05-27 012:15:34", "IsActive" : true, "CalendarCulture" : "Gregorian", "CreatedDate" : "2020-03-21 10:15:40", "CustomerNumber" : "123456", "Email" : "sample@example.com", "BillFirstName" : "John", "BillMiddleName" : "G", "BillLastName" : "Doe", "BillCompany" : "ACME Inc.", "AfterMaxRetriesAction" : "Disable", "Custom01" : "customValue1", "Custom02" : "customValue2", "Custom03" : "customValue3" }

/GetUpcomingPaymentDates

Returns a list of upcoming payment dates (up to 100) for a specific schedule.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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.



ScheduleId

Yes

string



The ID of the schedule to retrieve.



NumberOfPayments

Yes

integer



The number of payment dates to retrieve.

An integer between 1 and 100 (inclusive)

CalendarCulture

No

string

Gregorian

The culture the dates should be returned in.

Gregorian, Hebrew

Sample Request

1 2 3 4 5 6 7 8 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "ScheduleId" : "c123456_s123456", "NumberOfPayments" : 12, "CalendarCulture" : "Gregorian", "ShowDeleted" : false }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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.



UpcomingPaymentDates

string[]

The upcoming payment dates for the specified schedule in the format yyyy-mm-dd.



Sample Response

1 2 3 4 5 6 7 8 9 10 { "RefNum": "r1234567890", "Result": "S", "Error": "", "UpcomingPaymentDates" : [ "2020-01-01", "2020-02-01", "2020-03-01" ] }

/ListSchedules

Returns a list of schedules that are sorted by creation date (ascending or descending order). You can use search filters to narrow the search results that are returned.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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 schedules.



SortOrder

No

string

Ascending

The list order. Order is determined by schedule 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

  • Active

  • Amount

  • IntervalCount

  • CustomerId

  • ScheduleId

  • BillFirstName

  • BillMiddleName

  • BillLastName

  • BillName

  • Email

  • BillCompany

  • CustomerNumber

  • ScheduleName

  • Description

  • IntervalType

  • StartDate

  • PaymentsRemaining



Sample Request

1 2 3 4 5 6 7 8 9 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "NextToken" : "", "PageSize" : 500, "Filters" : { "IsDeleted" : false } }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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.



Schedules

object[]

An array of schedule objects. Refer to the /GetSchedule endpoint for the values that are returned for each schedule.

Note: The ScheduleRule field is not returned by this endpoint for each schedule.



NextToken

string

A token to include in the next request to get the next set of results.



Sample Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "RefNum": "r1234567890", "Result": "S", "Error": "", "Schedules" : [ { "ScheduleId": "c123456_s123456", "Revision": 5, "CustomerId": "c123456", "FailedTransactionRetryTimes": 5, "StartDate": "2018-04-27", "Amount": 0.03, "TotalPayments": 3, "PaymentsProcessed": 2, "IntervalType": "Day", "IntervalCount": 1, "LastTransactionStatus": "Approved", "LastProjectedPaymentDate": "2019-05-16", "InitialRunTime": "2019-05-16 01:03:50", "LastRunTime": "2019-06-19 01:03:48", "CalendarCulture": "Gregorian", "CreatedDate": "2018-04-26 16:33:27.571", "CustomerNumber": "1", "BillFirstName": "John", "BillLastName": "Smith", "BillCompany": "ACME Inc." } ] }

Transaction Endpoints

/ProcessTransaction

Processes a single payment transaction for a customer. You can specify a backup payment method to use should the initial payment fail. If desired, you can have the system send an email receipt of the transaction to the customer.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Parameter

Required

Type

Default Value

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



Customer's unique ID number.

PaymentMethodId

Yes*

string



The ID of the payment method to use for the transaction.

*Required if using an existing payment method.

Amount

Yes

decimal



The amount of the transaction.

Tax

No

decimal

 

The tax portion that is included in the total transaction amount

PaymentDetails

No*

object



The details for a new method of payment.

*Required if not using an existing payment method.

Note: Refer to the /CreatePaymentMethod endpoint for available and required fields.

UseBackupPaymentMethods

No

boolean

false

Indicates that the system should try another card if the default card fails.

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.

Description

No

string



Additional data sent with the transaction.

AllowDuplicates

No

boolean

false

A flag indicating whether to disable duplicate detection. Useful for testing, but it is not suggested that this be set to true in production.

CustReceipt

No

boolean



A flag that can be set to send the receipts to the email address set in Email for the customer.

Cvv

No

string



The CVV value for the transaction.

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.

*This field is 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.

*This field is required if BillFirstName and BillCompany are not passed in.

BillCompany

Yes*

string



Customer's company for their billing profile.

*This field is 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.

CustomXX

No

string



Custom fields (19 available) used for custom data, such as customer comments and so forth.

Custom01 is reserved. Use Custom02 - Custom20.

Currency

No

string



Currency code for the transaction

TransactionType

No

string

sale

The type of transaction to run.

Sample Request

1 2 3 4 5 6 7 8 9 10 11 12 13 14 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "PaymentMethodId" : "c123456_pm123456", "Amount" : 1.23, "PaymentDetails" : null, "UseBackupPaymentMethods" : false, "Invoice" : "1234567", "PONumber" : "1234567", "Description" : "Sample One Time Transaction", "AllowDuplicates" : false, "Cvv" : "123", "BillStreet" : "123 Main St." }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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.



GatewayRefnum

string

The gateway reference number for the transaction.



GatewayStatus

string

The status of the transaction passed back by the gateway.



GatewayErrorMessage

string

The error message for the transaction passed back by the gateway, if the status indicates an error.



Sample Response

1 2 3 4 5 6 7 8 { "RefNum": "r1234567890", "Result": "S", "Error": "", "GatewayRefnum" : "1234567890" "GatewayStatus" : "Success", "GatewayErrorMessage" : "" }

/GetTransaction

Returns the details of an existing transaction, such as transaction date and customer ID. Also returned is the transaction's processing status and any error messages from the gateway.

POST

Request Body (JSON)

Parameter

Required

Type

Description

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.

TransactionId

Yes

string

The ID of the transaction to retrieve

Sample Request

1 2 3 4 5 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "TransactionId" : "c123456_s123456_t123456" }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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.



TransactionId

string

The ID of the retrieved transaction.



ScheduleId

string

The ID of the schedule the transaction was run for.



CustomerId

string

The ID of the customer the transaction was run for.



PaymentMethodId

string

The ID of the payment method used in the transaction.



TransactionDate

string

The date the transaction was run.



GatewayRefNum

string

The reference number generated by the gateway for the transaction.



GatewayStatus

string

The transaction processing status returned by the gateway.



GatewayError

string

The error message return by the gateway if GatewayStatus indicates an error.



Sample Response

1 2 3 4 5 6 7 8 9 10 11 12 13 { "RefNum": "r1234567890", "Result": "S", "Error": "", "TransactionId": "c123456_s123456_t123456", "ScheduleId": "c123456_s123456", "CustomerId": "c123456", "PaymentMethodId": "c123456_pm123456", "TransactionDate": "2019-08-02 15:06:57", "GatewayRefNum": "1234567890", "GatewayStatus": "Approved", "GatewayError": "" }

/ListTransactions

Returns a list of transactions, which are sorted by transaction date (ascending or descending order). You can use specific search criteria to define which transactions to return.

POST

Request Body (JSON)

Parameter

Required

Type

Default Value

Description

Valid Values

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 transactions.



SortOrder

No

string

Ascending

The list order. Order is determined by the date the transaction ran.

Ascending, Descending

Filters

No

object



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:

  • IsApproved

  • FromDate

  • ToDate

  • CustomerId

  • ScheduleId

  • PaymentMethodId

  • TransactionId



Sample Request

1 2 3 4 5 6 7 8 9 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "NextToken" : "", "PageSize" : 500, "Filters" : { "IsApproved" : true } }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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.



Transactions

object[]

An array of transaction objects.

Refer to the /GetTransaction endpoint for the values that are returned for each transaction.



NextToken

string

A token to include in the next request to get the next set of results.



Sample Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 { "RefNum": "r1234567890", "Result": "S", "Error": "", "Transactions" : [ { "TransactionId": "c123456_s123456_t123456", "ScheduleId": "c123456_s123456", "CustomerId": "c123456", "PaymentMethodId": "c123456_pm123456", "TransactionDate": "2019-08-02 15:06:57", "GatewayRefNum": "1234567890", "GatewayStatus": "Approved" }, { "TransactionId": "c123456_s123456_t123456", "ScheduleId": "c123456_s123456", "CustomerId": "c123456", "PaymentMethodId": "c123456_pm123456", "TransactionDate": "2019-08-07 16:34:16", "GatewayRefNum": "1234567891", "GatewayStatus": "Approved" }, ] }

Merchant Endpoints

/UpdateMerchant

Changes the recurring report settings for the merchant, which includes:

  • Email address 

  • Enabled status

  • Show Details setting 

POST

Request Body (JSON)

Parameter

Required

Type

Description

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 current revision number of the record, if this value is incorrect the update will fail.

ScheduleReportSettings

Yes

object

The schedule report settings for the merchant:

  • Enabled (boolean): A flag indicating if the system should send the report.

  • EmailAddresses (array of string): One or more email addresses that will be sent the report.

  • ShowDetails (boolean): A flag indicating if the system should send the detailed version of the report with transaction details. The system can send the detailed version sent only if there are 500 transactions or less.

MaxRetriesReachedNotification

No

object

Settings for an email notification when a schedule reaches the maximum number of retries in an interval.

  • Enabled (boolean): A flag indicating if the system should send the email notification.

  • EmailAddresses (array of string): One or more email addresses that will be sent the notification.

Note: Values are only updated if they are not set to null. To clear the EmailAddresses an empty array must be passed in.

Sample Request

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "SoftwareName" : "ACME Inc.", "SoftwareVersion" : "1.0", "Revision" : 1, "ScheduleReportSettings" : { "Enabled" : true, "EmailAddresses" : [ "sample@example.com", "sample2@example.com" ], "ShowDetails" : true }, "MaxRetriesReachedNotification" : { "Enabled" : true, "EmailAddresses" : [ "sample@example.com", "sample2@example.com" ] } }

Response Body (JSON)

Parameter

Type

Description

Valid Values

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

1 2 3 4 5 { "RefNum": "r1234567890", "Result": "S", "Error": "" }

/DescribeMerchant

Returns the merchant's current configuration for recurring report settings (see /UpdateMerchant).

POST

Request Body (JSON)

Parameter

Required

Type

Description

Parameter

Required

Type

Description

SoftwareName

Yes

string

The name of the software making the request.

SoftwareVersion

Yes

string

The version of th