Recurring API

Overview

The Cardknox Recurring API enables you to process recurring transactions by using the Cardknox gateway. The API uses simple commands to make integrating with Cardknox a seamless experience. You can use the API to schedule recurring payments for any interval, such as weekly, monthly, every 30 days, annually, and more. Plus, you can easily create customer profiles that can be synchronized with multiple payment schedules and/or payment methods.

Credentials

Cardknox uses the same URL for both sandbox and live accounts, differentiated only by the authentication key, called the xKey. When you sign up for a Cardknox account, you will receive a sandbox xKey that identifies your account and enables you to perform test transactions. You will receive a separate xKey for your live account.

Include the following required information with your request to create a sandbox account:

  • Your Cardknox credentials – xKey
  • API version – xVersion (the current version is 1.0.0)
  • The name of your software – xSoftwareName
  • The version of your software – xSoftwareVersion

Endpoint

Send transactions to Cardknox at: https://api.cardknox.com/recurring

Response Parameters

Transactions submitted to the Cardknox API return all parameters of the newly created item along with one or more standard response parameters. The following table lists the standard response parameters and their values.

Standard Response Parameters

FieldName Description Values
xReportData Data returned in reports
xRecordsReturned Amount of records retrieved when running a report 20
xStatus Request status Valid values:

  • E
  • S
xResult Result verbiage Valid values:

  • Error
  • Success
xError Error message if applicable See xErrorCode
xErrorCode Error code 00000
xRecurringRefNum Request Reference Number r10000001

CUSTOMER

Add

xCommand = customer:add
Use this command to add a new customer record, which can then be linked to future payment methods and schedules. Creating a new schedule without linking it to an existing customer automatically generates a new customer for you.

Customer Add Command

Variable Required Description Sample Data
xBillCity No Customer’s city for their billing profile Anytown
xBillCompany No Customer’s company name for their billing profile Acme
xBillCountry No Customer’s country for their billing profile USA
xBillFirstName No Customer’s first name for their billing profile John
xBillLastName No Customer’s last name or family name for their billing profile Doe
xBillMiddleName No Customer’s middle name or middle initial for their billing profile Max
xBillMobile No Customer’s mobile number for their billing profile 8005551111
xBillPhone No Customer’s phone number for their billing profile 8005551212
xBillState No The customer’s state for their billing profile. NY
xBillStreet No Customer’s street address for their billing profile 123 Any Street
xBillStreet2 No Customer’s street address second line for their billing profile Apt 4B
xBillZip No Customer’s Zip code or postal code for their billing profile 12345
xCustomerNumber No Merchant’s internal customer identifier 8005551111
xEmail No Customer’s email address example@example.com
xFax No Customer’s fax number 8885551212
xCustomerNotes No Notes pertaining to the customer VIP customer
xCustomerCustom01 No Custom fields (20 available) used for custom data such as customer comments, etc. Use xCustomerCustom01 through xCustomerCustom20.

Update Command

xCommand = customer:update

Use this command to update existing customer information.

Note: All fields with values must be passed in (even fields that are not being updated). Any fields not passed in are treated as being set to blank.

Customer Update Command

Variable Required Description Sample Data
xCustomerID Yes Customer’s unique ID number c10000001
xCustomerNumber No Merchant’s internal customer identifier 1234
xEmail No Customer’s email address example@example.com
xBillFirstName No Customer’s first name for their billing profile John
xBillMiddleName No Customer’s middle name or middle initial for their billing profile Max
xBillLastName No Customer’s last name or family name for their billing profile Doe
xBillCompany No Customer’s company name for their billing profile Acme
xBillStreet No Customer’s street address for their billing profile 123 Any Street
xBillStreet2 No Customer’s street address second line for their billing profile Apt 4B
xBillCity No Customer’s city for their billing profile Anytown
xBillState No Customer’s state for their billing profile NY
xBillZip No Customer’s Zip code or postal code for their billing profile 12345
xBillCountry No Customer’s country for their billing profile USA
xBillPhone No Customer’s phone number for their billing profile 8005551212
xBillMobile No Customer’s mobile number for their billing profile 8005551111
xFax No Customer’s fax number 8885551212
xCustomerNotes No Notes pertaining to the customer VIP customer
xDefaultPaymentMethodID No Indicates the default payment method used to process the transaction P10000001
xCustomerCustom01 No Custom fields (20 available) used for custom data such as customer comments, etc. Use xCustomerCustom01 through xCustomerCustom20.

Remove Command

xCommand = customer:remove

Use this command to remove a customer record.

Note: The customer record is not completely deleted from the database; instead, the removed property is set to true.
Customers with active schedules cannot be removed.

Customer Remove Command

Variable Required Description Sample Data
xCustomerID Yes Customer’s unique ID number c10000001

Get

xCommand = report:customer
Use this command to retrieve a customer’s details.

Customer Get Command

Variable Required Description Sample Data
xCustomerID Yes Customer’s unique ID number c10000001
xRemoved No Indicates whether to return deleted rows

True/False value

Default value is False.

FALSE

Find

xCommand = report:customers
Use this command to find customers using specific search parameters.

Customer Find Command

Variable Required Description Sample Data
xCustomerID No Customer’s unique ID number c10000001
xCustomerNumber No Merchant’s internal customer identifier 1234
xEmail No Customer’s email address example@example.com
xBillFirstName No Customer’s first name for their billing profile John
xBillMiddleName No Customer’s middle name or middle initial for their billing profile Max
xBillLastName No Customer’s last name or family name for their billing profile Doe
xBillCompany No Customer’s company name for their billing profile Acme
xBillStreet No Customer’s street address for their billing profile 123 Any Street
xBillStreet2 No Customer’s street address second line for their billing profile Apt 4B
xBillCity No Customer’s city for their billing profile Anytown
xBillState No Customer’s state for their billing profile NY
xBillZip No Customer’s Zip code or postal code for their billing profile 12345
xBillCountry No Customer’s country for their billing profile USA
xBillPhone No Customer’s phone number for their billing profile 8005551212
xBillMobile No Customer’s mobile number for their billing profile 8005551111
xRemoved No Indicates whether to return deleted rows

True/False value

Default value is False.

FALSE

Transaction

xCommand = customer:transaction
Use this command to process a single transaction from the API using either the xPaymentMethodID parameter or just the xCustomerID parameter (in which case the customer’s default payment method is used).

You can pass in the xUseBackupPaymentMethods parameter to specify trying other payment methods belonging to the customer if the transaction is declined.

Customer Transaction Command

Variable Required Description Sample Data
xAmount Yes Amount charged 10
xCustomerID No* Customer’s unique ID number

* Required if the xPaymentMethodID is not passed in, or if the xUseBackupPaymentMethods is passed in as TRUE.

c10000001
xPaymentMethodID No* Payment method’s unique ID

* Required if the xCustomerID is not passed in.

pm10000001
xUseBackupPaymentMethods No Indicates whether to use the customer’s other payment methods for the charge if the transaction is declined

True/False value

Note: This is not allowed if using a new payment method that has not been saved.

FALSE
xAllowDuplicate No Option to allow duplicate transactions

True/False value

This is typically used only for testing.

FALSE
xToken No Cardknox token that references a previously used payment method to use for the charge (if not using a payment method that has been saved with the Recurring API) 30g96686q944q388507nn1p580084gn9
xTokenType No* The xToken payment type

* Required if the xToken is passed in.

Valid values:

  • CC = Credit card
  • Check = Check
xName No* Name on the customer’s account

* Required for ACH (check) transactions if the xToken is passed in.

John Smith
xStreet No The billing street address of the cardholder. 123 Main St
xZip No The billing zip code of the cardholder. 11111
xDescription No Additional data optionally passed along for reporting. Transaction description
xInvoice No Customer’s invoice number for the transaction.

Use xInvoice when available for improved duplicate handling (recommended).

123456A
xPONum No Customer’s purchase order number for the transaction. 123485B
xCustom01 No Custom field used for custom data such as customer comments, etc. Register01
xCustom02 No Custom field used for custom data such as customer comments, etc. Register02
xShipFirstName No Customer’s first name for their shipping profile John
xShipMiddleName No Customer’s middle name or initial for their shipping profile. Max
xShipLastName No Customer’s last/family name for their shipping profile Doe
xShipCompany No Customer’s company name for their shipping profile Acme
xShipStreet No Customer’s street address for their shipping profile 123 Any Street
xShipStreet2 No Customer’s street address 2nd line for their shipping profile Apt 4b
xShipCity No Customer’s city for their shipping profile Anytown
xShipState No Customer’s state for their shipping profile NY
xShipZip No Customer’s ZIP code for their shipping profile 11111
xShipCountry No Customer’s country for their shipping profile USA
xShipPhone No Customer’s phone number for their shipping profile 8005551212
xShipMobile No Customer’s mobile number for their shipping profile 8005551111
xShipEmail No Customer’s shipping email address for their shipping profile example@example.com

PAYMENT METHOD

Add Command

xCommand = paymentmethod:add
Use this command to add a new payment method to a customer’s account profile.

Payment Method Add Command

Variable Required Description Sample Data
xCustomerID Yes Customer’s unique ID number c10000001
xToken Yes Cardknox token that references a previously used payment method to use for the charge 30g96686q944q388507nn1p580084gn9
xTokenType Yes The xToken payment type Valid values:

  • CC = Credit card
  • Check = Check
xTokenAlias No Custom name for the xToken Ending in 1111
xExp No* Credit card expiration date

* Required if xToken is an iFields token and xTokenType is ‘cc’

Format: MMYY (e.g., 1220 for December 2020)
xRouting No* ACH payment routing number

* Required if xToken is an iFields token and xTokenType is ‘ach’

1234567890
xName No* Name on the customer’s account

* Required for ACH (check) transactions.

0
xStreet No The billing street address of the cardholder. 123 Any Street
xZip No The billing zip code of the cardholder. 11111
xSetToDefault No Sets this payment method as the default payment method

True/False value

Note: If there are no other payment methods, this method is automatically set as the default.

TRUE

Update

xCommand = paymentmethod:update

Use this command to update an existing payment method.
Note: All fields with values must be passed in (even the fields that are not being updated). Any fields not passed in are treated as being set to blank.

Payment Method Update Command

Variable Required Description Sample Data
xPaymentMethodID Yes Payment method’s unique ID pm10000001
xName No* Name on the customer’s account

* Required for ACH (check) transactions.

* Required if the xTokenType is “check” and must be identical to what is currently saved.

0
xToken Yes* Cardknox token that references a previously used payment method

* Must be identical to what is currently saved.

30g96686q944q388507nn1p580084gn9
xTokenType Yes* The xToken payment type

* Must be identical to what is currently saved.

Valid values:

  • CC = Credit card
  • Check = Check
xTokenAlias No Custom name for the xToken Ending in 1111
xName No* Name on the customer’s account

* Required for ACH (check) transactions.

0
xStreet No The billing street address of the cardholder. 123 Any Street
xZip No The billing zip code of the cardholder. 1111
xSetToDefault No Sets this payment method as the default payment method

True/False value

Note: If there are no other payment methods, this method is automatically set as the default.

TRUE
xExp No Expiration date

The expiration date can be updated for payment methods with xTokenType of “cc” (Credit card).

1224

Remove

xCommand = paymentmethod:remove
Use this command to remove a payment method.

Note: The payment method is not completely deleted from the database; instead, the removed property is set to true. Customers with active schedules cannot be removed.

Payment Method Remove Command

Variable Required Description Sample Data
xPaymentMethodID Yes Payment method’s unique ID pm10000001

Get

xCommand = report:paymentmethod
Use this command to retrieve details of a payment method.

Payment Method Get Command

Variable Required Description Sample Data
xPaymentMethodID Yes Payment method’s unique ID pm10000001
xRemoved No Indicates whether to return deleted rows.

True/False value

Default value is False.

FALSE

Find

xCommand = report:paymentmethods
Use this command to find payment methods using specific search parameters.

Payment Method Find Command

Variable Required Description Sample Data
xCustomerID No Customer’s unique ID number c10000001
xName No Name on the customer’s account

* Required for ACH (check) transactions.

0
xRemoved No Indicates whether to return deleted rows

True/False value

Default value is False.

FALSE

SCHEDULE

Add Command

xCommand = schedule:add

Use this command to initiate a new recurring payment schedule.

Schedules have two main parameters: xIntervalType and xIntervalCount. You can set xIntervalType to day, week, month, or year. The xIntervalCount parameter determines the number of times the xIntervalType should pass before the next payment schedule is triggered.

For example, to process a charge every two weeks, set xIntervalType to week and set xIntervalCount to 2, indicating that two weeks should pass before initiating a new charge. To process a charge every 10 days, set xIntervalType to day and set xIntervalCount to 10, indicating that 10 days should pass before initiating a new charge.

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.

Note: You can create schedules for existing customers only. Alternatively, you can create a customer record and a schedule together in one request if you already have an xToken from a customer. You can do this by passing in the customer’s last name, token, token alias, and token type in addition to the schedule-specific parameters.

Unless the xStartDate parameter was included to specify a future start date for the schedule, the first charge will take place immediately by default.

Schedule Add Command

Variable Required Description Sample Data
xIntervalType Yes Type of time interval Valid values:

  • Day
  • Week
  • Month
  • Year
xAmount Yes Total amount of each transaction 9.99
xTotalPayments No* Total count of scheduled payment occurrences, including the initial payment

* If left blank, the count is indefinite.

12
xToken No* Cardknox token that references a previously used payment method

* Required if xCustomerID is not passed through.

30g96686q944q388507nn1p580084gn9
xTokenType No* The xToken payment type

* Required if xCustomerID is not passed through.

Valid values:

  • CC = Credit card
  • Check = Check
xTokenAlias No Custom name for the xToken Ending in 1111
xExp No* Credit card expiration date

* Required if xToken is an iFields token and xTokenType is ‘cc’

Format: MMYY (e.g., 1220 for December 2020)
xRouting No* ACH payment routing number

* Required if xToken is an iFields token and xTokenType is ‘ach’

1234567890
xCustomerID No* Customer’s unique ID number

* Required if linking the schedule to an existing customer.

xCustomerNumber No Merchant’s internal customer identifier 1234
xEmail No Customer’s email address example@example.com
xBillFirstName No Customer’s first name for their billing profile John
xBillLastName No Customer’s last name or family name for their billing profile Doe
xBillMiddleName No Customer’s middle name or middle initial for their billing profile Max
xBillCompany No Customer’s company name for their billing profile Acme
xBillStreet No Customer’s street address for their billing profile 123 Any Street
xBillStreet2 No Customer’s street address second line for their billing profile Apt 4B
xBillCity No Customer’s city for their billing profile Anytown
xBillState No Customer’s state for their billing profile NY
xBillZip No Customer’s Zip code or postal code for their billing profile 12345
xBillCountry No Customer’s country for their billing profile USA
xBillPhone No Customer’s phone number for their billing profile 8005551212
xBillMobile No Customer’s mobile number for their billing profile 8005551111
xFax No Customer’s fax number 8885551212
xDescription No Additional data (optional) Monthly Schedule
xScheduleName No Merchant’s internal schedule identifier Schedule01
xIntervalCount No Number of time periods to elapse before the payment schedule is re-triggered

Examples:

For every 28 days, set xIntervalType to day and set xIntervalCount to 28.

For every other month, set xIntervalType to month and set xIntervalCount to 2.

Default value is 1.

3
xRetryAmount No Number of days to try again before rescheduling to the next run time if the transaction fails.

Default value is 5.

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

5
xSkipSab No Indicates whether to process payments on the Sabbath and Jewish holidays

True/False value

Default value is False.

FALSE
xCalendarCulture No Type of calendar to use when executing month and year interval types

Default value is Gregorian.

Valid values:

  • Gregorian
  • Hebrew
xUseDefaultCardOnly No Indicates that the system should not try another card if the default card fails

True/False value

Default value is False.

TRUE
xStartDate No Schedule start date in YYYY-MM-DD format

The start date must be within one year.

Default value is today’s date.

2020-01-01
xExpireDate No Schedule expiration date in YYYY-MM-DD format

* May not be used together with xTotalPayments.

2020-06-30
xAllowDecline No Create the schedule even if the initial payment fails

True/False value

* Can be used only if the xStartDate is set to today’s date.

FALSE
xAllowDuplicate No Allow duplicate transactions

True/False value

This is typically used only for testing.

TRUE

Update

xCommand = schedule:update
Use this command to update an existing schedule.

Note 1: You can make updates only for information that does not change the actual schedule. The actual schedule cannot be updated.

Note 2: All fields with values must be passed in (even the fields that are not being updated). Any fields not passed in are treated as being set to blank.

Schedule Update Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number s100000001
xDescription No Additional data (optional) Monthly Schedule
xScheduleName No Merchant’s internal schedule identifier Schedule01
xSkipSab No Indicates whether to process payments on the Sabbath and Jewish holidays

True/False value

Default value is False.

FALSE
xUseDefaultCardOnly No Indicates that the system should not try another card if the default card fails

True/False value

Default value is False.

TRUE
xTotalPayments No Total count of scheduled payment occurrences, including the initial payment

It can be updated to at least the number of payments processed or higher.

* If left blank, the count is indefinite.

1
xStartDate No Schedule start date in YYYY-MM-DD format

The start date must be within one year.

Default value is today’s date.

2020-01-01
xExpireDate No Schedule expiration date in YYYY-MM-DD format

The xExpireDate can only be updated if the schedule has not expired.

* May not be used together with xTotalPayments.

2020-06-30
xAllowDuplicate No Allow duplicate transactions

True/False value

This is typically used only for testing.

FALSE
xAllowDecline No Create the schedule even if the initial payment fails

True/False value

* Not allowed to be updated, must be the same as what is currently saved.

FALSE
xIntervalType Yes* Type of time interval

* Not allowed to be updated, must be the same as what is currently saved.

Valid values:

  • Day
  • Week
  • Month
  • Year
xIntervalCount No* Number of time periods to elapse before the payment schedule is re-triggered

Examples:

For every 28 days, set xIntervalType to day and set xIntervalCount to 28.

For every other month, set xIntervalType to month and set xIntervalCount to 2.

Default value is 1.

* Not allowed to be updated, must be the same as what is currently saved.

3
xAmount Yes* Total amount of each transaction

* Not allowed to be updated, must be the same as what is currently saved.

9.99
xCalendarCulture No* Type of calendar to use when executing month and year interval types

Default value is Gregorian.

* Not allowed to be updated, must be the same as what is currently saved.

Valid values:

  • Gregorian
  • Hebrew

Disable

xCommand = schedule:disable
Use this command to stop, pause, cancel, or inactivate a schedule.

Schedule Disable Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number s100000001

Enable

xCommand = schedule:enable
Use this command to start a previously disabled schedule.

Schedule Enable Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number s100000001

Remove

xCommand = schedule:remove
Use this command to remove a schedule.

Note: The schedule is not completely deleted from the database, but rather the removed property is set to true.

Schedule Remove Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number s100000001

Get

xCommand = report:schedule
Use this command to retrieve a schedule’s details.

Schedule Get Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number s100000001
xRemoved No Indicates whether to return deleted rows

True/False value

Default value is False

FALSE

Find

xCommand = report:schedules
Use this command to find schedules by using specific search parameters.

Schedule Find Command

Variable Required Description Sample Data
xScheduleID No Schedule reference number s100000001
xCustomerID No Customer’s unique ID number c10000001
xCustomerNumber No Merchant’s internal customer identifier 1234
xEmail No Customer’s email address example@example.com
xBillFirstName No Customer’s first name for their billing profile John
xBillMiddleName No Customer’s middle name or middle initial for their billing profile Max
xBillLastName No Customer’s last name or family name for their billing profile Doe
xBillName No Combination of the customer’s first, middle, and last name John Max Doe
xScheduleName No Schedule name Plan A
xDescription No Description sent with the transaction
xTotalPayments No Total count of scheduled payment occurrences, including the initial payment
xAmount No Transaction amount
xIntervalType No Type of time interval Valid values:

  • Day
  • Week
  • Month
  • Year
xIntervalCount No Number of time periods to elapse before the payment schedule is re-triggered

Examples:

For every 28 days, set xIntervalType to day and set xIntervalCount to 28.

For every other month, set xIntervalType to month and set xIntervalCount to 2.

Default value is 1.

* Can only be passed in together with xIntervalType.

xStartDate No Schedule start date in YYYY-MM-DD format

The start date must be within one year.

Default value is today’s date.

2020-01-01
xRemoved No Indicates whether to return deleted rows

True/False value

Default value is False.

FALSE
xActive No Return active schedules (optional)

True/False value

True returns all active schedules; False returns all inactive schedules.

Default value is True.

TRUE
xIncludeCustomerInfo No Determines whether to include customer and payment method information

True/False value

Default value is False.

Can be useful for reports.

TRUE

Get Upcoming

xCommand = report:scheduleupcoming
Use this command to get the number of upcoming payment dates for the schedule. If the count exceeds the number of payments remaining, the system returns only the number of remaining payment dates.

Schedule Get Upcoming Command

Variable Required Description Sample Data
xScheduleID Yes Schedule reference number. s100000001
xUpcomingPaymentsCount No Number of upcoming payment dates to return

Default value is 12.

10

TRANSACTION

Find

xCommand = report:transactions
Use this command to find transactions by using specific search parameters.

Transaction Find Command

Variable Required Description Sample Data
xApproved No Indicates whether to return approved transactions

True/False value

* If left blank, returns all transactions (approved and not approved).

TRUE
xBeginDate No Transaction begin date 2019-01-15
xEndDate No Transaction end date 2019-01-31