Overview

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

Customer Endpoints

Base URL

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

/CreateCustomer

Add a new customer record, which can then be linked to payment methods and schedules.

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerNumber	No	string	Merchant’s internal customer identifier.
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.

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., customers that are not deleted will not be returned).

{
    "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, 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": ""
}

/GetCustomer

Retrieves a customer.

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., customers that are not deleted will not be returned).

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

{
    "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.

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.

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"
        }
    ]
}

Payment Method Endpoints

/CreatePaymentMethod

Add a new payment method to a customer’s account profile.

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
CustomerId	Yes	string	The ID of the customer to update.
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.

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

Retrieve details of a payment method.

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
PaymentMethodId	Yes	string	The ID of the payment method to retrieve.
ShowDeleted	No	boolean	A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., payment methods that are not deleted will not be returned).

{
    "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 and time the payment method was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).

{
    "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.

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

Return payment methods based on specific search parameters.

Request Body (JSON)

Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
PageSize	No	integer	100	The maximum number of items to retrieve for this request.
NextToken	No	string		A token that can be sent 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.
IsDefaultPaymentMethod	boolean	If there is more than one payment method for a specific customer one of the payment methods will have a flag.	True, False

{
    "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

Creates a 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.

Examples:
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.
To process a charge every 10 days, set IntervalType to day and set IntervalCount to 10. This specifies that 10 days should pass before initiating a new charge.

Unsuccessful Payments
If an attempted payment is unsuccessful (i.e., the card is declined), the system reschedules the charge for the following day. This can be done up to five times, provided that the rescheduled payment doesn’t overlap into the next payment cycle. After five unsuccessful attempts, or if rescheduling the payment as above will overlap into the next payment cycle, this individual payment will be canceled, but the entire schedule remains in effect.

Request Body (JSON)

Parameter	Required	Type	Default Value	Description	Valid Values
SoftwareName	Yes	string		The name of the software making the request.
SoftwareVersion	Yes	string		The version of the software making the request.
CustomerId	Yes*	string		Customer’s unique ID number. *Required if linking the schedule to an existing customer.
NewCustomer	Yes*	object		The customer details. Refer to the /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 /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.
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.
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 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. Unless the StartDate parameter was included to specify a future start date for the schedule, the first charge will take 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, 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

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 Amount field and CustomerId field cannot be updated (and are not listed in the parameter table below). You cannot update inactive schedules.
The following fields can be updated at any point:

• AfterMaxRetriesAction
• CustomXX
• CustReceipt
• DaysBetweenRetries
• Description
• Invoice
• PONumber
• RetryAmount
• ScheduleName
• SkipSaturdayAndHolidays
• UseDefaultPaymentMethodOnly
• TotalPayments

Any fields that are not set, use their default values. If a field is not set and does not have a default value, it is removed.

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

Restart a schedule that was previously disabled.

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

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

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

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

Request Body (JSON)

Parameter	Required	Type	Description
SoftwareName	Yes	string	The name of the software making the request.
SoftwareVersion	Yes	string	The version of the software making the request.
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 the details for a schedule.

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	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.
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
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 /AddSchedule 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 our 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	The date and time the schedule was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).
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, etc. Custom01 is reserved.

{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}

/GetUpcomingPaymentDates

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

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

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.

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

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.

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

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

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.

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

Merchant Endpoints

/UpdateMerchant

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

• Email address
• Enabled status
• Show Details setting

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

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

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
  }