No payment integration is too complex.
Across all Cardknox products we use a key (
xKey) to identify on what account to process a specific transaction. Each Cardknox product doc will guide you where to set the
xKey(for example: in the body of the request along with all other parameters, in the request header as “Authorization”, in the app settings etc.). You will have a unique
xKeyfor sandbox and production accounts.
Tokenization is the process of replacing sensitive payment data with a non-sensitive algorithm-generated
stringcalled a token (
xToken). Each time you send a card or bank account number with a transaction, the response will include a token represented by
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
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:
- For check transactions:
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:
- 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
xDuplicateWindowwith the number of minutes on a transaction request to override the default 10-minute timeframe of the duplicate checker.
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.
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. The field names in parentheses are the fileds for the reporting API.
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.
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.
(AllowPartialAuth must be set to True)
Alternative AVS Responses
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.