Customer and 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
Customer and 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 has been a major change that overhauls the entire API.
Example: https://api.cardknox.com/v2​
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
{
    "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"
Response Body (JSON)
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"
}
/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/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"
}
Response Body (JSON)
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": ""
}
/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
{
    "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, 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"
}
/DeleteCustomer
Deletes a customer record. You cannot delete a customer who has an active recurring 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.
CustomerId
Yes
string
The ID of the customer to update.
Sample Request
{
    "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, 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": ""
}
/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 do not 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
{
	"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, 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.
​
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
{
    "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

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