Recurring API

Overview

The Cardknox Recurring API, designed in the RESTful architectural style, lets you process recurring transactions through the Cardknox gateway based on customized schedules. You can create recurring schedules along with customers and payment methods. Additionally, you can process single transactions for a customer and change a merchant's settings for recurring schedule reports.

Authorization

All requests require passing in an Authorization header. The value of the Authorization header should be your gateway API key. Contact Cardknox at [email protected], and we will send you an API key via email.

Versioning

Recurring API V2 is versioned to allow stability for integrators and flexibility for Cardknox to continue making improvements.

Major Version

The URL contains the major version number parameter. This version number would only be changed if there is a major change that overhauls the entire API.

Minor Version

This version number is incremented when a breaking change to the existing API is implemented (for example, a change to how requests are processed or how responses are sent back).
The minor version is passed in the X-Recurring-Api-Version header: X-Recurring-Api-Version = 2.1

Request Method

Method:
​
The Cardknox gateway requires the POST method to be used for enhanced security.
We do not support the GET method.

Base URL

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

Customer Endpoints

/CreateCustomer

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

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerNumber
No
string
Merchant's internal customer identifier.
CustomerNotes
No
string
Notes pertaining to the customer.
Email
No
string
Customer's email address.
Fax
No
string
Customer's fax number.
BillFirstName
Yes*
string
Customer's first name for their billing profile.
*Required if BillLastName and BillCompany are not passed in.
BillMiddleName
No
string
Customer's middle name or middle initial for their billing profile.
BillLastName
Yes*
string
Customer's last name or family name for their billing profile.
*Required if BillFirstName and BillCompany are not passed in.
BillCompany
Yes*
string
Customer's company name for their billing profile.
*Required if BillFirstName and BillLastName are not passed in.
BillStreet
No
string
Customer's street address for their billing profile.
BillStreet2
No
string
Customer's street address second line for their billing profile.
BillCity
No
string
Customer's city for their billing profile.
BillState
No
string
Customer's state for their billing profile.
BillZip
No
string
Customer's ZIP code or postal code for their billing profile.
BillCountry
No
string
Customer's country for their billing profile.
BillPhone
No
string
Customer's phone number for their billing profile.
BillMobile
No
string
Customer's mobile number for their billing profile.
ShipFirstName
No
string
Customer’s first name for their shipping profile.
ShipMiddleName
No
string
Customer’s middle name or initial for their shipping profile.
ShipLastName
No
string
Customer’s last/family name for their shipping profile.
ShipCompany
No
string
Customer’s company name for their shipping profile.
ShipStreet
No
string
Customer’s street address for their shipping profile.
ShipStreet2
No
string
Customer’s street address second line for their shipping profile.
ShipCity
No
string
Customer’s city for their shipping profile.
ShipState
No
string
Customer’s state for their shipping profile.
ShipZip
No
string
Customer’s ZIP code for their shipping profile.
ShipCountry
No
string
Customer’s country for their shipping profile.
ShipPhone
No
string
Customer’s phone number for their shipping profile.
ShipMobile
No
string
Customer’s mobile number for their shipping profile.
ShipEmail
No
string
Customer’s shipping email address for their shipping profile.
CustomerCustomXX
No
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.

Sample Request

1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"CustomerNumber" : "123456",
5
"CustomerNotes" : "Vip Customer",
6
"Email" : "[email protected]",
7
"Fax" : "",
8
"BillFirstName" : "John",
9
"BillMiddleName" : "G",
10
"BillLastName" : "Doe",
11
"BillCompany" : "ACME Inc.",
12
"BillStreet" : "123 Main Street",
13
"BillStreet2" : "STE 1",
14
"BillCity" : "AnyTown",
15
"BillState" : "NY",
16
"BillCountry" : "USA",
17
"BillZip" : "11218",
18
"BillPhone" : "",
19
"BillMobile" : "",
20
"ShipFirstName" : "John",
21
"ShipMiddleName" : "G",
22
"ShipLastName" : "Doe",
23
"ShipCompany" : "ACME Inc.",
24
"ShipStreet" : "123 Main Street",
25
"ShipStreet2" : "STE 1",
26
"ShipCity" : "AnyTown",
27
"ShipState" : "NY",
28
"ShipCountry" : "USA",
29
"ShipZip" : "11218",
30
"ShipPhone" : "",
31
"ShipMobile" : "",
32
"ShipEmail" : "[email protected]",
33
"CustomerCustom01" : "MyCustomValue",
34
"CustomerCustom02" : "MyCustomValue2",
35
"CustomerCustom03" : "MyCustomValue3"
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
CustomerId
integer
The created customer ID.
​
Sample Response
{ "RefNum": "r1234567890", "Result": "S", "Error": "", "CustomerId": "c1234567890" }

/UpdateCustomer

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

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
Revision
Yes
integer
The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
CustomerId
Yes
string
The ID of the customer to update.
CustomerNumber
No
string
Merchant's internal customer identifier.
CustomerNotes
No
string
Notes pertaining to the customer.
Email
No
string
Customer's email address.
Fax
No
string
Customer's fax number.
BillFirstName
Yes*
string
Customer's first name for their billing profile.
*Required if BillLastName and BillCompany are not passed in.
BillMiddleName
No
string
Customer's middle name or middle initial for their billing profile.
BillLastName
Yes*
string
Customer's last name or family name for their billing profile.
*Required if BillFirstName and BillCompany are not passed in.
BillCompany
Yes*
string
Customer's company name for their billing profile.
*Required if BillFirstName and BillLastName are not passed in.
BillStreet
No
string
Customer's street address for their billing profile.
BillStreet2
No
string
Customer's street address second line for their billing profile.
BillCity
No
string
Customer's city for their billing profile.
BillState
No
string
Customer's state for their billing profile.
BillZip
No
string
Customer's ZIP code or postal code for their billing profile.
BillCountry
No
string
Customer's country for their billing profile.
BillPhone
No
string
Customer's phone number for their billing profile.
BillMobile
No
string
Customer's mobile number for their billing profile.
ShipFirstName
No
string
Customer’s first name for their shipping profile.
ShipMiddleName
No
string
Customer’s middle name or initial for their shipping profile.
ShipLastName
No
string
Customer’s last/family name for their shipping profile.
ShipCompany
No
string
Customer’s company name for their shipping profile.
ShipStreet
No
string
Customer’s street address for their shipping profile.
ShipStreet2
No
string
Customer’s street address second line for their shipping profile.
ShipCity
No
string
Customer’s city for their shipping profile.
ShipState
No
string
Customer’s state for their shipping profile.
ShipZip
No
string
Customer’s ZIP code for their shipping profile.
ShipCountry
No
string
Customer’s country for their shipping profile.
ShipPhone
No
string
Customer’s phone number for their shipping profile.
ShipMobile
No
string
Customer’s mobile number for their shipping profile.
ShipEmail
No
string
Customer’s shipping email address for their shipping profile.
CustomerCustomXX
No
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"Revision" : 1,
5
"CustomerId" : "c123456",
6
"CustomerNumber" : "123456",
7
"CustomerNotes" : "Vip Customer",
8
"Email" : "[email protected]",
9
"Fax" : "",
10
"BillFirstName" : "John",
11
"BillMiddleName" : "G",
12
"BillLastName" : "Doe",
13
"BillCompany" : "ACME Inc.",
14
"BillStreet" : "123 Main Street",
15
"BillStreet2" : "STE 1",
16
"BillCity" : "AnyTown",
17
"BillState" : "NY",
18
"BillCountry" : "USA",
19
"BillZip" : "11218",
20
"BillPhone" : "",
21
"BillMobile" : "",
22
"ShipFirstName" : "John",
23
"ShipMiddleName" : "G",
24
"ShipLastName" : "Doe",
25
"ShipCompany" : "ACME Inc.",
26
"ShipStreet" : "123 Main Street",
27
"ShipStreet2" : "STE 1",
28
"ShipCity" : "AnyTown",
29
"ShipState" : "NY",
30
"ShipCountry" : "USA",
31
"ShipZip" : "11218",
32
"ShipPhone" : "",
33
"ShipMobile" : "",
34
"ShipEmail" : "[email protected]",
35
"CustomerCustom01" : "MyCustomValue",
36
"CustomerCustom02" : "MyCustomValue2",
37
"CustomerCustom03" : "MyCustomValue3"
38
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": ""
5
}
Copied!

/GetCustomer

Retrieves the details of a specific customer.

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to retrieve.
ShowDeleted
No
boolean
A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e. customers that are not deleted will not be returned).
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"CustomerId" : "c1234567890",
5
"ShowDelete" : false
6
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Revision
integer
The revision number of the customer record.
​
CreatedDate
string
The date and time the customer was created, returned in ISO 8601 format (yyyy-MM-dd HH:mm:ss.fff).
​
CustomerId
string
The ID of the customer to update.
​
CustomerNumber
string
Merchant's internal customer identifier.
​
CustomerNotes
string
Notes pertaining to the customer.
​
Email
string
Customer's email address.
​
Fax
string
Customer's fax number.
​
BillFirstName
string
Customer's first name for their billing profile.
​
BillMiddleName
string
Customer's middle name or middle initial for their billing profile.
​
BillLastName
string
Customer's last name or family name for their billing profile.
​
BillCompany
string
Customer's company name for their billing profile.
​
BillStreet
string
Customer's street address for their billing profile.
​
BillStreet2
string
Customer's street address second line for their billing profile.
​
BillCity
string
Customer's city for their billing profile.
​
BillState
string
Customer's state for their billing profile.
​
BillZip
string
Customer's ZIP code or postal code for their billing profile.
​
BillCountry
string
Customer's country for their billing profile.
​
BillPhone
string
Customer's phone number for their billing profile.
​
BillMobile
string
Customer's mobile number for their billing profile.
​
ShipFirstName
string
Customer’s first name for their shipping profile.
​
ShipMiddleName
string
Customer’s middle name or initial for their shipping profile.
​
ShipLastName
string
Customer’s last/family name for their shipping profile.
​
ShipCompany
string
Customer’s company name for their shipping profile.
​
ShipStreet
string
Customer’s street address for their shipping profile.
​
ShipStreet2
string
Customer’s street address second line for their shipping profile.
​
ShipCity
string
Customer’s city for their shipping profile.
​
ShipState
string
Customer’s state for their shipping profile.
​
ShipZip
string
Customer’s ZIP code for their shipping profile.
​
ShipCountry
string
Customer’s country for their shipping profile.
​
ShipPhone
string
Customer’s phone number for their shipping profile.
​
ShipMobile
string
Customer’s mobile number for their shipping profile.
​
ShipEmail
string
Customer’s shipping email address for their shipping profile.
​
CustomerCustomXX
string
Custom fields (20 available) used for custom data such as customer comments and so forth. Use CustomerCustom01 through CustomerCustom20.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": "",
5
"CustomerId": "c123456",
6
"Revision": 1,
7
"CustomerNotes": "Vip Customer",
8
"CustomerNumber": "123456",
9
"DefaultPaymentMethodId": "",
10
"CreatedDate": "2019-08-20 14:30:57.578",
11
"Email": "[email protected]",
12
"BillFirstName": "John",
13
"BillMiddleName": "G",
14
"BillLastName": "Doe",
15
"BillCompany": "ACME Inc.",
16
"BillStreet": "123 Main Street",
17
"BillStreet2": "STE 1",
18
"BillCity": "AnyTown",
19
"BillState": "NY",
20
"BillZip": "11218",
21
"BillCountry": "USA",
22
"ShipFirstName": "John",
23
"ShipMiddleName": "G",
24
"ShipLastName": "Doe",
25
"ShipCompany": "ACME Inc.",
26
"ShipStreet": "123 Main Street",
27
"ShipStreet2": "STE 1",
28
"ShipCity": "AnyTown",
29
"ShipState": "NY",
30
"ShipZip": "11218",
31
"ShipCountry": "USA",
32
"ShipEmail": "[email protected]",
33
"CustomerCustom01": "MyCustomValue",
34
"CustomerCustom02": "MyCustomValue2",
35
"CustomerCustom03": "MyCustomValue3"
36
}
Copied!

/DeleteCustomer

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

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to update.
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"CustomerId" : "c123456"
5
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": ""
5
}
Copied!

/ListCustomers

Lists customers created by a merchant.

Request Body (JSON)

Parameter
Required
Type
Default Value
Description
Valid Values
SoftwareName
Yes
string
​
The name of the software making the request.
​
SoftwareVersion
Yes
string
​
The version of the software making the request.
​
PageSize
No
integer
100
The maximum number of items to retrieve for this request.
​
NextToken
No
string
​
A token that can be sent in to the following request to get the next set of customers.
​
SortOrder
No
string
Ascending
The list order. Order is determined by customer creation date.
Ascending, Descending
Filters
No
object
{
"IsDeleted" : false
}
Filters that can be applied to limit the result set.
Filters will remove any items that don't contain the string for that filter value. If there are multiple filters applied the item must match all of them.
Available filters:
  • CustomerId
  • CustomerNumber
  • IsDeleted
  • Email
  • BillName
  • BillFirstName
  • BillLastName
  • BillMiddleName
  • BillCompany
  • BillStreet
  • BillStreet2
  • BillCity
  • BillState
  • BillZip
  • BillCountry
  • BillPhoneNumber
  • BillPhone
  • BillMobile
  • BillFax
​
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"NextToken" : "",
5
"PageSize" : 500,
6
"Filters" : {
7
"BillFirstName" : "John",
8
"BillState" : "NY"
9
}
10
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Customers
object[]
An array of customer objects.
Refer to the /GetCustomer endpoint for the values that are returned for each customer.
​
NextToken
string
A token to include in the next request to get the next set of results.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": "",
5
"Customers" : [
6
{
7
"CustomerId" : "c123456",
8
"Revision" : 1,
9
"BillFirstName" : "John",
10
"BillLastName" : "Doe",
11
"BillState" : "NY"
12
},
13
{
14
"CustomerId" : "c123457",
15
"Revision" : 1,
16
"BillFirstName" : "Johnathan",
17
"BillLastName" : "Doe",
18
"BillState" : "NY"
19
}
20
]
21
}
Copied!

Payment Method Endpoints

/CreatePaymentMethod

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

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
CustomerId
Yes
string
The ID of the customer to update with the new payment method.
Token
Yes
string
Cardknox token that references a previously used payment method to use for the charge.
TokenType
Yes
string
The Token payment type.
TokenAlias
No
string
Custom name for the Token.
Exp
Yes*
string
Credit card expiration date.
*Required if Token is an iFields token and TokenType is cc.
Routing
Yes*
string
ACH payment routing number.
*Required if Token is an iFields token and TokenType is ach.
Name
No
string
Name on the customer's account.
*Required for ACH (check) transactions.
Street
No
string
Customer's street address for their billing profile.
Zip
No
string
Customer's ZIP code or postal code for their billing profile.
SetAsDefault
No
boolean
Sets this payment method as the default payment method.
Note: If there are no other payment methods, this method is automatically set as the default.
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"CustomerId" : "c123456",
5
"Token" : "pm4408q3327hq551h5h51058qh6n87mn",
6
"TokenType" : "cc",
7
"TokenAlias" : "",
8
"Exp" : "1220",
9
"Routing" : "",
10
"Name" : "",
11
"Street" : "",
12
"Zip" : "",
13
"SetAsDefault" : false
14
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
PaymentMethodId
string
The ID of the created payment method.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": "",
5
"PaymentMethodId": "c123456_pm123456
6
}
Copied!

/UpdatePaymentMethod

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

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
Revision
Yes
integer
The revision number of the record to update. If this does not match the current revision number of the record, the update will fail.
PaymentMethodId
Yes
string
The ID of the payment method to update.
TokenAlias
No
string
Custom name for the Token.
Exp
Yes*
string
Credit card expiration date.
*Required if Token is an iFields token and TokenType is cc.
Routing
Yes*
string
ACH payment routing number.
*Required if Token is an iFields token and TokenType is ach.
Name
No*
string
Name on the customer's account.
*Required for ACH (check) transactions.
Street
No
string
Customer's street address for their billing profile.
Zip
No
string
Customer's ZIP code or postal code for their billing profile.
SetAsDefault
No
boolean
Sets this payment method as the default payment method.
Note: If there are no other payment methods, this method is automatically set as the default.
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"Revision" : 1,
5
"CustomerId" : "c123456",
6
"TokenAlias" : "",
7
"Exp" : "1220",
8
"Routing" : "",
9
"Name" : "",
10
"Street" : "",
11
"Zip" : "",
12
"SetAsDefault" : false
13
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
Sample Response
1
{
2
"RefNum": "r1234567890",
3
"Result": "S",
4
"Error": ""
5
}
Copied!

/GetPaymentMethod

Retrieves an existing payment method.

Request Body (JSON)

Parameter
Required
Type
Description
SoftwareName
Yes
string
The name of the software making the request.
SoftwareVersion
Yes
string
The version of the software making the request.
PaymentMethodId
Yes
string
The ID of the payment method to retrieve.
ShowDeleted
No
boolean
A flag that can be set to retrieve deleted items. If set to true, only deleted items can be retrieved (i.e., payment methods that are not deleted will not be returned).
Sample Request
1
{
2
"SoftwareName" : "ACME Inc.",
3
"SoftwareVersion" : "1.0",
4
"PaymentMethodId" : "c123456_pm123456",
5
"ShowDeleted" : false
6
}
Copied!

Response Body (JSON)

Parameter
Type
Description
Valid Values
Result
char
The result of the API call. S represents success, E represents an error.
S, E
RefNum
string
A unique request ID.
​
Error
string
If the Result parameter contains a value of E, this parameter will contain any relevant error messages.
​
PaymentMethodId
string
The ID of the payment method.
​
Revision
number
The revision number of the record to update. If this does not match the current revision number of the record the update will fail.
​
Token
string
Cardknox token that references a previously used payment method to use for the charge.
​
TokenType
string
The Token payment type.
CC, Check
TokenAlias
string
Custom name for the Token.
​
Exp
string
Credit card expiration date (in MMYY format).
​