Customer and Recurring API

Overview 
The Cardknox Customer and Recurring API, allows you to set up customers and process single and/or recurring payments associated with specific customers through the Cardknox gateway. The API can be built into your system dashboard so you can process transactions and monitor rich data analytics.
Our Customer and Recurring API gives you the ability to create custom recurring schedules with precise parameters, add customer records, and store payment methods. You’ll also be able to process single transactions for a customer.
Authorization
All requests require passing along an authorization header. The value of the authorization header should be your gateway API key, which can be obtained through the Cardknox Portal.
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, that can 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.
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.
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.
​
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
/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
{
    "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, 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.
​
PaymentMethodId
string
The ID of the created payment method.
​
Sample Response
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": "",
    "PaymentMethodId": "c123456_pm123456
}
/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
No
string
Credit card expiration date.
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
{
    "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, 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
{
    "RefNum": "r1234567890",
    "Result": "S",
    "Error": ""
}
/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
{
    "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, 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.
​
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).
​
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 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).
​
Sample Response
{
    "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
Removes a payment method from the customer’s record. This will fail if the payment method is the customer's only payment method and there are active 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.
PaymentMethodId
Yes
string
The ID of the payment method to retrieve.
Sample Request
{
    "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, 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": ""
}
/ListPaymentMethods
Return payment methods based on specific search parameters.
Request Body (JSON)