Introduction

Authentication / Credentials
Across all of our products, we use a xKey to authenticate and identify which account to process a specific transaction.
Each Cardknox product documentation will guide you where to set your unique xKey.

Usage Examples:
In the body of a request, along with all other parameters
In a request header as “Authorization”
In our application settings
You will have a unique xKey for both sandbox and production accounts.
Tokenization
Tokenization is the process of replacing sensitive payment data with a non-sensitive algorithm-generated string called a token (xToken). Each time you send a card or bank account number with a transaction, the response will include a token represented by xToken.
As a merchant’s PCI-compliance scope significantly increases when storing sensitive data, the best practice is to store the token in your database rather than sensitive data. You use the token for follow-up transactions.
With this approach, sensitive data will not be at risk if a data breach occurs on your local system.
Cardknox references the payment information on our servers associated with the token sent and processes the transaction. A new token will be returned on every new transaction processed.
You can reuse the original token multiple times. However, you should use the new returned token in the following scenarios:
If the card has a new expiration date.
If a response flag indicates, the card was updated/modified.
A token only stores the data sent with a transaction that is necessary to process future transactions. Tokens store the expiration date, street address, and zip code for credit card transactions. Tokens do not store customer information, such as billing or contact information, other than street address and ZIP codes, sometimes required for validation by Address Verification System (AVS).
Cardknox servers will never store the 3 or 4 digit CVV number as per PCI regulations and, in extension, is not associated with tokens.
Only when a cardholder is processing an initial transaction, with a physical card in hand, is CVV data used.
Tokens can be used only on the account it was generated on unless linked to another account via cross tokenization 
You can request account linking for tokenization via Support.
The best practice is to generate tokens on one account and link all other accounts to your first account instead of generating tokens for each.
To generate a token for a payment method without processing a transaction, use the save command.
For credit card transactions: cc:save.
For check transactions: check:save.
Duplicate Handling
The Cardknox Gateway automatically blocks a transaction considered a “duplicate” of another transaction based on certain identifying features and if the transactions are within 10 minutes (default timeframe) of each other.

The transaction will error with a message of: Duplicate Transaction
Identifying Features:
Key
Credit Card Number
Transaction Amount
Invoice Number
Check Account Number
Check Routing Number
You can allow the transaction to go through by changing any of the above. Alternatively, you can pass through "xAllowDuplicate = True" in the transaction request.
You can set xDuplicateWindow with the number of minutes on a transaction request to override the default 10-minute timeframe of the duplicate checker.
By default, you can set it up to 1440 (24 Hours) max.
Your account can be set to allow up to 43200 (30 Days) via Support.
Batches
Each day, batch files capture all of your transactions.
Cardknox automatically “batches out” once the batch cutoff time is reached (determined by the processing bank) and sends the related transactions to the bank for settlement. A batch report is available in the Cardknox Merchant Portal.
Sandbox Account Testing Info and Triggers
A sandbox account is used to simulate transactions as if it is in production. It is designed to act exactly like a production account. However, there can sometimes be unique account setups where the production account won't match the sandbox account exactly to a T. Therefore, we recommend that you do all your testing in the sandbox account and then doing one final test when going live and swapping out your sandbox key with your production key.
Credit Card and Account Numbers
You can use any valid card number to submit transactions while using a sandbox account. The card will not actually be charged as long as you are using your sandbox key. To avoid your system unintentionally going live while still configured with your sandbox credentials, transactions in the sandbox account are limited to $10. You can bypass that limit by using the below numbers.
Credit Card
Check (ACH)
Card Type
Card Number
Visa
4444333322221111
Visa
4111111111111111
Mastercard
5454545454545454
Discover
6011208703331119
American Express
370276000431054
Account Number
Routing Number
999999999
021000021 (any valid routing number)
Triggers
Declined Transaction
Partial Auth
Delay/Timeout
CVV Responses
​
xName
Response
Decline
Declined
​
(AllowPartialAuth must be set to True)
xAmount
AuthAmount
7.5
1.5
7.23
1.23
​
xDescription
Behavior
Response
Delay
Response delayed 30 seconds
Approved
Timeout
Response delayed 30 seconds
Try Again
Timeout_Extended
Response delayed 120 seconds
Try Again
xCVV
CVV Result
CVV Result Code
​
​
​
123
M
Match
1234
M
Match
111
M
Match
1111
M
Match
222
N
No Match
2222
N
No Match
555
P
Not Processed
444
S
Should be on card, but not so indicated
8888
U
Issuer Not Certified
7777
X
No Response from Association
AVS Responses
Alternative AVS Responses
xStreet
xZip
AvsResultCode
xAvsResult
111
11111
YYY
Address: Match & 5 Digit Zip: Match
999
99999
NNN
Address: No Match & 5 Digit Zip: No Match
111
111111111
YYX
Address: Match & 9 Digit Zip: Match
111
99999
YNA
Address: Match & 5 Digit Zip: No Match
999
111111111
NYW
Address: No Match & 9 Digit Zip: Match
999
11111
NYZ
Address: No Match & 5 Digit Zip: Match
888
88888
XXR
Retry / System Unavailable
777
77777
XXU
Address Information not verified for domestic transaction
666
66666
XXS
Service Not Supported
AvsResultCode
xAvsResult
Y
Address: Match & 5 Digit Zip: Match
Z
No Match & 5 Digit Zip: Match
A
Address: Match & 5 Digit Zip: No Match
N
Address: No Match & 5 Digit Zip: No Match
X
Address: Match & 9 Digit Zip: Match
W
Address: No Match & 9 Digit Zip: Match
R
Retry / System Unavailable
S
Service Not Supported
The Cardknox gateway does not require developers to go through a certification process. We do provide a process to self-certify if developers choose to do so. You can download the Cardknox Self-certification Guide.
Response Parameters
Transactions that are submitted to the Cardknox API will return a response with one or more of the fields below. Below are the standard parameters and their values.
Field Name
Description
Values
xResult (xGatewayResult)
Transaction status
A
E
D
xStatus (xResponseResult)
Result verbiage
Approved
Error
Declined
xError (xResponseError)
Error message, if applicable
See error code
xErrorCode
Error code
Most common error codes:
00000 = Approved
01332 = Duplicate Transaction
1334 = Declined Transaction
01479 = Invalid Card
​See All Error Codes​
xRefNum
Cardknox transaction Reference Number
Note: xRefnum is always returned regardless of the outcome of the transaction.
​
xInvoice
Invoice number
​
xExp
The card expiration number
​
xAuthCode (xResponseAuthCode)
Authorization code, approved transactions only
​
xBatch (xResponseBatch)
Batch into which transaction will settle
​
xAvsResultCode (xResponseAVSCode)
The Address Verification Service (AVS) response code
YYY = Address: Match & 5 Digit Zip: Match
NYZ = Address: No Match & 5 Digit Zip: Match
YNA = Address: Match & 5 Digit Zip: No Match
NNN = Address: No Match & 5 Digit Zip: No Match
XXU = Address Information not verified for domestic transaction
YYX = Address: Match & 9 Digit Zip: Match
NYW = Address: No Match & 9 Digit Zip: Match
XXR = Retry / System Unavailable
XXS = Service Not Supported
XXW = Card Number Not On File
XXE = Address Verification Not Allowed For Card Type
XXG = Global Non-AVS participant
YYG = International Address: Match & Zip: Not Compatible
GGG = International Address: Match & Zip: Match
YGG = International Address: Not Compatible & Zip: Match
Alternative Responses
AvsResultCodexAvsResultYAddress: Match & 5 Digit Zip: MatchZNo Match & 5 Digit Zip: MatchAAddress: Match & 5 Digit Zip: No MatchNAddress: No Match & 5 Digit Zip: No MatchXAddress: Match & 9 Digit Zip: MatchWAddress: No Match & 9 Digit Zip: MatchRRetry / System UnavailableSService Not Supported
xAvsResult
AVS verbiage
See AVS result code
xCvvResultCode (xResponseCVVCode)
Card Code Verification (CCV) response code
M = Match
N = No Match
P = Not Processed
S = Should be on card, but not so indicated
U = Issuer Not Certified
X = No Response from Association
xCvvResult
CVV verbiage
See CVV result code
xAuthAmount
The total amount authorized, inclusive of tax and tip (if applicable).
​
xMaskedCardNumber
A masked version of the credit card used for the transaction
​
xCardType
Type of credit card used for the transaction
Unknown
EBT
GiftCard
Amex
Visa
MasterCard
Discover
Diners
JCB
xName
Name of card holder
John
xToken
Token returned for use with future transaction.
gh3hpn46mp0g785915gn7h79q502976n
xCurrency
Currency the transaction was processed as
USD
Next - API
Transaction API
Last modified 1mo ago
Export as PDF
Copy link
Contents
Authentication / Credentials
Tokenization
Duplicate Handling
Batches
Sandbox Account Testing Info and Triggers
Triggers
Response Parameters