Overview

Credentials
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 xKey for sandbox and production accounts.
Tokenization
Tokenization is the process of replacing sensitive payment data with a non-sensitive algorithm-generated string called a token. Each time a card or bank account number is sent with a transaction, the Cardknox response will include a token represented by xToken. As a merchant’s PCI-compliance scope is greatly increased when storing sensitive data, best-practice is to store the token in your database instead of the sensitive data and use the token for follow-up transactions. With this approach, if a data breach occurs on your local system, sensitive data will not be at risk.
When a token is sent along with a transaction, Cardknox references the payment information on our servers associated with that token and processes the transaction. Each time a transaction is processed, a new token will be returned.
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 that the card was updated
A token only stores the data sent with a transaction that is necessary to process future transactions. It does not store general customer information such as billing and contact information.
As an example, for a credit card transaction, only the credit card number, expiration date, street address, and zip code (which can be required for Address Verification System (AVS) validation) are stored with the token.
Info
Note: The 3 or 4 digit CVV number is never stored on Cardknox servers as per PCI regulations, and in extension, is not associated with tokens. CVV data is only used when processing initial transactions where the cardholder is generating the transaction with their physical card in hand.
​
Info
Tokens can only be used on the account it was generated on unless the accounts are linked for cross tokenization (account linking for tokenization can be requested from support). Best practice is to generate tokens on one of the accounts and and link all other accounts to that first account vs generating tokens on multiple accounts.
To generate a token for a payment method without processing a transaction, use the save command.
For a credit card transaction cc:save. For check transactions, check:save.
Duplicate handling
The Gateway will automatically block a transaction that is 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 amount 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. The account can be set to allow up to 43200 (30 Days).
Batches
Each day, all captured transactions are added to a batch file. Once the batch cutoff time is reached (determined by the processing bank), Cardknox automatically “batches out”, which sends the related transactions to the bank for settlement. A batch report is available in the Cardknox portal.

Next - API

Transaction API

Last modified 15d ago

Copy link

Contents