Comment on page
Customer and Recurring API
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.
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 provide you with an API key.
Customer and Recurring API V2 is versioned to allow stability for integrators and flexibility for Cardknox to continue making improvements.
The URL contains the major version number parameter. This version number would only be changed if there has been a major change that overhauls the entire API.
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
Method:
​
The Cardknox gateway requires the POST method to be used for enhanced security.
We do not support the GET method.
Add a new customer record, which can then be linked to payment methods and schedules.
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 . |
{
"SoftwareName" : "ACME Inc.",
"SoftwareVersion" : "1.0",
"CustomerNumber" : "123456",
"CustomerNotes" : "Vip Customer",
"Email" : "[email protected]",
"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" : "[email protected]",
"CustomerCustom01" : "MyCustomValue",
"CustomerCustom02" : "MyCustomValue2",
"CustomerCustom03" : "MyCustomValue3"
Parameter | Type | Description | Valid Values |
Result | char | The result of the API call. S represents success, E represents 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"
}
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.
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/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
{
"SoftwareName" : "ACME Inc.",
"SoftwareVersion" : "1.0",
"Revision" : 1,
"CustomerId" : "c123456",
"CustomerNumber" : "123456",
"CustomerNotes" : "Vip Customer",
"Email" : "[email protected]",
"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" : "[email protected]",
"CustomerCustom01" : "MyCustomValue",
"CustomerCustom02" : "MyCustomValue2",
"CustomerCustom03" : "MyCustomValue3"
}
Parameter | Type | Description | Valid Values |
Result | char | The result of the API call. S represents success, E represents 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
{
"RefNum": "r1234567890",
"Result": "S",
"Error": ""
}
Retrieves the details of a specific customer.
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
{
"SoftwareName" : "ACME Inc.",
"SoftwareVersion" : "1.0",
"CustomerId" : "c1234567890",
"ShowDelete" : false
}
Parameter | Type | Description | Valid Values |
Result | char | The result of the API call. S represents success, E represents 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 initial for their billing profile. | ​ |
BillLastName | string | Customer's last/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
{
"RefNum": "r1234567890",
"Result": "S",
"Error": "",
"CustomerId": "c123456",
"Revision": 1,
"CustomerNotes": "Vip Customer",
"CustomerNumber": "123456",
"DefaultPaymentMethodId": "",
"CreatedDate": "2019-08-20 14:30:57.578",
"Email": "[email protected]",
"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": "[email protected]",
"CustomerCustom01": "MyCustomValue",
"CustomerCustom02": "MyCustomValue2",
"CustomerCustom03": "MyCustomValue3"
}
Deletes a customer record. You cannot delete a customer who has an active recurring schedule.
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
{
"SoftwareName" : "ACME Inc.",
"SoftwareVersion" : "1.0",
"CustomerId" : "c123456"
}
Parameter | Type | Description | Valid Values |
Result | char | The result of the API call. S represents success, E represents error. | S, E |
RefNum | string | A unique request ID. |