Recurring API – Version 2.0

Description

The Recurring API provides the ability to run transactions on a customized schedule.
Click Here For Recurring API Version 1 Documentation

Authorization

All requests require passing in an Authorization header. The value of the Authorization header should be your gateway API key.

Versioning

Major Version
The URL contains a version number parameter indicating the API’s major version. This version number would only be changed if there is a major change overhauling the entire API.

Minor Version
Each request requires passing in an X-Recurring-Api-Version header. This version number will be 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).

Current Versions

Major Version Minor Version Supported Release Date Changes
v2 2.0 In Production 2019-11-13 Initial version

Endpoints

Base URL

The base URL for all requests is https://api.cardknox.com/v2

/CreateCustomer

Creates a new customer.

POST

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.
Customer Notes 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.

*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 name 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 Second line of the customer’s street address 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 Second line of the customer’s street address 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 (postal 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, etc. Use CustomerCustom01 through CustomerCustom20. 
 {
    "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
Result char The result of the API call. S represents success, and 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 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "CustomerId": "c1234567890"
}

/UpdateCustomer

Updates an existing customer.

POST

Request Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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 in ISO 8601 format.
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.

*This field is required if xBillLastName and xBillCompany are not passed in.
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.

*This field is required if xBillFirstName and xBillCompany are not passed in.
BillCompany string Customer’s company name for their billing profile.

*This field is required if xBillFirstName and xBillLastName are not passed in.
BillStreet string Customer’s street address for their billing profile.
BillStreet2 string Second line of the customer’s street address 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 Second line of the customer’s street address 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 (postal 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, etc. Use CustomerCustom01 through CustomerCustom20. 



{
    "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
Result char The result of the API call. S represents success, and 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 in ISO 8601 format.
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.

*This field is required if xBillLastName and xBillCompany are not passed in.
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.

*This field is required if xBillFirstName and xBillCompany are not passed in.
BillCompany string Customer’s company name for their billing profile.

*This field is required if xBillFirstName and xBillLastName are not passed in.
BillStreet string Customer’s street address for their billing profile.
BillStreet2 string Second line of the customer’s street address 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 Second line of the customer’s street address 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 (postal 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, etc. Use CustomerCustom01 through CustomerCustom20. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/GetCustomer

Retrieves a customer.

POST

Request Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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 in ISO 8601 format.
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.

*This field is required if xBillLastName and xBillCompany are not passed in.
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.

*This field is required if xBillFirstName and xBillCompany are not passed in.
BillCompany string Customer’s company name for their billing profile.

*This field is required if xBillFirstName and xBillLastName are not passed in.
BillStreet string Customer’s street address for their billing profile.
BillStreet2 string Second line of the customer’s street address 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 Second line of the customer’s street address 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 (postal 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, etc. Use CustomerCustom01 through CustomerCustom20. 
{
    "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, and 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 in ISO 8601 format.
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.

*This field is required if xBillLastName and xBillCompany are not passed in.
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.

*This field is required if xBillFirstName and xBillCompany are not passed in.
BillCompany string Customer’s company name for their billing profile.

*This field is required if xBillFirstName and xBillLastName are not passed in.
BillStreet string Customer’s street address for their billing profile.
BillStreet2 string Second line of the customer’s street address 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 Second line of the customer’s street address 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 (postal 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, etc. Use CustomerCustom01 through CustomerCustom20. 
{
    "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

Updates an existing customer.

POST

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 delete. 
{
    "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, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/ListCustomers

Lists customers created by a merchant.

POST

Request Body (JSON)

Parameter Required Type 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 The maximum number of items to retrieve for this request.
NextToken No string A token that can be sent into the following request to get the next set of customers.
SortOrder No string The list order. The order is determined by the customer creation date. 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:

  • CustomerId

  • CustomerNumber

  • IsDeleted

  • EmailxBillName

  • BillFirstName

  • BillLastName

  • BillMiddleName

  • BillCompany

  • BillStreet

  • BillStreet2

  • BillCity

  • BillState

  • BillZip

  • BillCountry

  • BillPhoneNumber

  • BillPhone

  • BillMobile

  • BillFax

 

{
    "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, and 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. 
{
    "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"
        }
    ]
}

/CreatePaymentMethod

Creates a new payment method for a customer.

POST

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

 
{
    "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, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c123456_pm123456"
}

/UpdatePaymentMethod

Updates an existing payment method.

POST

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

 
{
    "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, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/GetPaymentMethod

Retrieves an existing payment method.

POST

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). 
{
    "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, and 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
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 (postal code) of the customer being billed.
CreatedDate string The date the payment method was created (in yyyy-MM-dd HH:mm:ss.fff format). 
{
    "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

Deletes a payment method. This will fail if the payment method is the customer’s default payment method.

POST

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. 
{
    "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, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/ListPaymentMethods

Lists payment methods.

POST

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 into the following request to get the next set of customers.
SortOrder No string The list order. The order is determined by the 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:

  • IsDeleted

  • CustomerId

  • PaymentMethodId

  • Token

  • TokenType

  • TokenAlias

 

{
    "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, and 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. 
{
    "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
        }
    ]
}

/CreateSchedule

Creates a schedule.

POST

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 /AddCustomer 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 /AddPaymentMethod 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.
Amount Yes decimal Total amount of each transaction.
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 transactions 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.

Set this value to 0 to not retry and just reset the payment date even if the transaction failed.

SkipSaturdayAndHolidays No boolean false Indicates whether to process payments on the Jewish 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.
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, ContinueNextInterva
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, etc.

Custom01 is reserved. Use Custom02 – Custom20. 

{
    "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, and 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). 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "ScheduleId" : "c123456_s123456"
}

/UpdateSchedule

Updates a schedule. 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
SoftwareName Yes string The name of the software making the request.
SoftwareVersion Yes string The version of the software making the request.
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 Yes* string The ID of the schedule to update.
TotalPayments No integer infinite Total count of scheduled payment occurrences, including the initial payment.

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.

Set this value to 0 to not retry and just reset the payment date even if the transaction failed.
SkipSatrudayAndHolidays No boolean false Indicates whether to process payments on the Jewish 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.
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, etc.

Custom01 is reserved. Use Custom02 – Custom20.

 
{
    "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
Result char The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/EnableSchedule

Enables a disabled schedule.

POST

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.
ScheduleId Yes string The ID of the schedule to enable. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "ScheduleId" : "c123456_s123456"
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/DisableSchedule

Disables an enabled schedule.

POST

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.
ScheduleId Yes string The ID of the schedule to disable. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "ScheduleId" : "c123456_s123456"
}

Response Body (JSON)

Parameter Type Description Valid Values
Result string The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/DeleteSchedule

Deletes a schedule.

POST

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.
ScheduleId Yes* string The ID of the schedule to delete. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "ScheduleId" : "c123456_s123456"
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/GetSchedule

Retrieves an existing schedule.

POST

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.
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). 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "ScheduleId" : "c123456_s123456",
    "ShowDeleted" : false
}

Response 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.
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). 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/GetUpcomingPaymentDates

Gets the upcoming payment dates for a schedule.

POST

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.
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 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "ScheduleId" : "c123456_s123456",
    "NumberOfPayments" : 12,
    "CalendarCulture" : "Gregorian",
    "ShowDeleted" : false
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "UpcomingPaymentDates" : [
        "2020-01-01",
        "2020-02-01",
        "2020-03-01"
    ]
}

/ListSchedules

Lists schedules.

POST

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 into the following request to get the next set of customers.
SortOrder No string The list order. The order is determined by the 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:

  • IsDeleted
  • Active
  • Amount
  • IntervalCount
  • CustomerId
  • ScheduleId
  • BillFirstName
  • BillMiddleName
  • BillLastName
  • BillName
  • Email
  • BillCompany
  • CustomerNumber
  • ScheduleName
  • Description
  • IntervalType
  • StartDate
  • PaymentsRemaining
 

{
    "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, and 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. 
{
    "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": "4/26/2018 1:20:20 PM",
            "CustomerNumber": "1",
            "BillFirstName": "John",
            "BillLastName": "Smith",
            "BillCompany": "ACME Inc."
        }
    ]
}

/ProcessTransaction

Processes a one-time transaction for a customer.

POST

Request Body (JSON)

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.
PaymentDetails No* object The details for a new method of payment.

*Required if not using an existing payment method.

Note: Refer to the /AddPaymentMethod 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 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 Second line of the customer’s street address 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 (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 Second line of the customer’s street address 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(postal 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, etc.

Custom01 is reserved. Use Custom02 – Custom20.
Currency No string The transaction currency.
TransactionType No string sale The type of transaction to run. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "CustomerId" : "c123456",
    "PaymentMethodId" : "c123456_pm123456",
    "Amount" : 1.23,
    "PaymentDetails" : null,
    "UseBackupPaymentMethods" : false,
    "Invoice" : "1234567",
    "PONumber" : "1234567",
    "Description" : "Sample One Time Transaction",
    "AllowDuplicates" : false,
    "CustReceipts" : false,
    "Cvv" : "123",
    "BillStreet" : "123 Main St."
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "GatewayRefnum" : "1234567890"
    "GatewayStatus" : "Success",
    "GatewayErrorMessage" : ""
}

/GetTransaction

Retrieves an existing transaction.

POST

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.
TransactionId Yes string The ID of the transaction to retrieve. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "TransactionId" : "c123456_s123456_t123456"
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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 who the transaction was run for.
PaymentMethodId string The ID of the payment method used in the transaction.
TransactionDate string The date on which 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 returned by the gateway if GatewayStatus indicates an error. 
{
  "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

Retrieves an existing transaction.

POST

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 into 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

 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "NextToken" : "",
    "PageSize" : 500,
    "Filters" : {
        "IsApproved" : true
    }
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
    "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"
        },
    ]
}

/UpdateMerchant

Updates a merchant.

POST

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.
ScheduleReportSettings Yes object The schedule report settings for the merchant. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0",
    "Revision" : 1,
    "ScheduleReportSettings" : {
        "Enabled" : true,
        "EmailAddresses" : [
            "sample@example.com",
            "sample2@example.com"
        ],
        "ShowDetails" : true
    }
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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. 
{
  "RefNum": "r1234567890",
  "Result": "S",
  "Error": ""
}

/DescribeMerchant

Retrieves a merchant’s configuration.

POST

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. 
{
    "SoftwareName" : "ACME Inc.",
    "SoftwareVersion" : "1.0"
}

Response Body (JSON)

Parameter Type Description Valid Values
Result char The result of the API call. S represents success, and 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 current revision number of the record.
ScheduleReportSettings object The schedule report settings for the merchant. 
{
  "RefNum": "r1234567890",
  "Result": "S",
  "Error": "",
  "ScheduleReportSettings" : {
    "Enabled" : true,
    "EmailAddress" : [
      "sample@example.com",
      "sample2@example.com"
    ],
    "ShowDetails" : true
  }
}

Appendixes

Appendix A – Schedule Rules

Name Type Description Valid Values
RuleType string The type of rule to create. On, Nth
DayOfWeek integer The day of the week to run the schedule on. 1 – 7
DayOfMonth integer The day of the month to run the schedule on. 1 – 31 for Gregorian schedules

1 – 30 for Hebrew schedules
MonthOfYear integer The month of the year to run the schedule on. 1 – 12 for Gregorian schedules

1 – 13 for Hebrew schedules
N integer The nth value to run the schedule on. Any positive or negative integer other than zero
NthOfType string The type that the nth value should be applied to. Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Day, Weekday, Weekend Day

RuleType
There are 2 types of rules, On and Nth.

On rules run on a specified day within the specified interval (for example, every Sunday, the 3rd of each month, or February 17th of each year).

Nth rules run on nth (or nth from last) of the specified interval (for example, the first weekday of each month, or the second to last Sunday of each month).

Restrictions

  • DayOfWeek, DayOfMonth, and MonthOfYear can only be used when RuleType is On.
  • DayOfWeek can only be used for weekly schedules.
  • DayOfMonth can only be used for monthly and yearly schedules.
  • MonthOfYear can only be used for yearly schedules.
  • N and NthOfType can only be used when RuleType is Nth.
  • Weekly schedules can only have a RuleType of On.
  • Daily schedules cannot use rule types.

Additional Notes

  • Weekdays begin with Monday and continue through Friday.
  • Weekends are Saturday and Sunday.
  • The following are the values for the days of the week:
    • Sunday = 1
    • Monday = 2
    • Tuesday = 3
    • Wednesday = 4
    • Thursday = 5
    • Friday = 6
    • Saturday = 7
  • The following are the values for MonthOfYear for the Hebrew calendar:
    • Tishrei = 1
    • Cheshvan = 2
    • Kislev = 3
    • Teves = 4
    • Shevat = 5
    • Adar = 6
    • (Adar Beis = 7 in a leap year)
    • Nisan = 7 (8 in a leap year)
    • Iyar = 8 (9 in a leap year)
    • Sivan = 9 (10 in a leap year)
    • Tamuz = 10 (11 in a leap year)
    • Av = 11 (12 in a leap year)
    • Elul = 12 (13 in a leap year)
  • Use a negative number as the value of N to run as the nth from last.
    • An N value of 1 indicates the first.
    • An N value of -1 indicates the last.
  • A schedule with an IntervalCount greater than 1 will first run on the next matching date and will skip intervals going forward.
    • Example: If the current date is January 1st, 2020 (a Wednesday) and the schedule rule says that it should run on the first Thursday of month with an IntervalCount of 2, the first run-time will be January 2nd 2020 and the second run-time will be on March 5th, 2020.
  • Schedules will begin running on the first matching date on or after the scheduled start date. If the start date is after the first matching date in the current period, it will begin the next interval period.
    • Example: A yearly schedule that runs on January 1st with a start date of January 2nd, 2020, will first run on January 1st of 2021.
  • If no schedule rule is passed in when creating a schedule, a default rule will be created based on the interval type. The default RuleType is On with the DayOfWeek, DayOfMonth, and MonthOfYear values set based on the start date.

Examples

A monthly schedule that runs every 3 months on the first weekday of the month:

{
  "IntervalType" : "Month",
  "IntervalCount" : 3,
  "ScheduleRule" : {
    "RuleType" : "Nth",
    "N" : 1,
    "NthOfType" : "Weekday"
  }
}

A yearly schedule that runs every year on January 1st:

{
  "IntervalType" : "Year",
  "IntervalCount" : 1,
  "ScheduleRule" : {
    "RuleType" : "On",
    "DayOfMonth" : 1,
    "MonthOfYear" : 1
  }
}

A weekly schedule that runs every other Monday:

{
  "IntervalType" : "Week",
  "IntervalCount" : 2,
  "ScheduleRule" : {
    "RuleType" : "On",
    "DayOfWeek" : 2
  }