Introduction

No payment integration is too complex.

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.

Best practices

• Transaction response Transaction responses contain valuable information that you can utilize. The most important one is xResult; this will inform your system if the transaction was approved or declined. xAuthAmount will indicate how much was actually authorized by the bank, so it is a good idea to make sure that it matches the requested amount. By default, transactions will only approve for the full amount. If the full amount is not available, the transaction will be declined. Every transaction will receive a unique xRefnum that is used to identify this unique transaction. It is helpful during troubleshooting and is also used in case of a follow-up transaction (void refund, etc.). It is a good idea to display this xRefNum to the user and add it to receipts. You can find a full list of available response parameters here.

• Logs

  When submitting transaction requests to the Cardknox gateway, it is highly recommended to log the full request and response, including both the content body and headers. By logging this information, you ensure that critical details are readily available. In the event of any questions or troubleshooting needs, providing this information to the Cardknox support team will significantly reduce the time required to assist you or resolve the issue.

• Declines When a payment fails, you will get a xResult of D or E. Typically, you would simply want to display the failure notification to the user and show them the xError in the response that may, at times, contain helpful information to identify the reason for the decline. You can choose to allow the user to try another card. There is no need to handle different error messages or error codes specifically.

• Duplicates It is a good idea to pass in a unique xInvoice with each transaction that is sent for processing so Cardknox can try to catch unintentional duplicate payments. You can also give the user an option to intentionally process a duplicate payment by incrementing the invoice number or adding xAllowDuplicate=true to the transaction request. You can see more about duplicate payment handling here.

Vendor Settings (optional)

A Vendor ID is a unique identifier associated with your vendor account. This feature is useful when you will be processing payments across multiple Cardknox accounts. It allows for specific settings to be configured on your vendor account, and these settings will be applied on transactions that include your Vendor ID in the transaction request. When using this feature, It is optimal to include your vendor ID across all transactions that you process on the Cardknox gateway.

Setup

Our support team can enable your vendor account and provide you with the ID.

Usage

To use Vendor settings, include the xVendorID = {yourvendorid} in the transactions request.

Features/Benefits

iFields key: Use a single iFields key across all your accounts.

Tokenization: Tokens can be used across accounts.

Licenses: Unlimited device licenses

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.

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. The field names in parentheses are the fileds for the reporting API.

Field Name	Description	Sample values
xResult (xGatewayResult)	Single character code indicating if the transaction was Approved or not. A = Approved E = Error D = Declined	A E D
xStatus (xResponseResult)	Verbiage indicating if the transaction was approved or not.	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 Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String
xInvoice	Invoice number
xExp	The card expiration number
xAuthCode (xResponseAuthCode)	Authorization code, for approved transactions only
xBatch (xResponseBatch)	Batch into which the 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 (xAmount)	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 DonorsFund OJC Pledger
xName	Name of cardholder	John
xToken	Token returned for use with future transaction	gh3hpn46mp0g785915gn7h79q502976n
xCurrency	Currency that the transaction was processed in	USD
xEntryMethod	Transaction method	Keyed EMV Swipe
xDate	Date and time the transaction was processed	1/1/2020 10:00:00 AM
xRefnumCurrent	Current reference number	Used for troubleshooting purposes only. Returned when using a command that modifies an existing transaction, such as cc:void, cc:capture, or cc:adjust.
xReviewed	This will be returned only if account is configured to return this response field.	Y = Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant will have chargeback protection. P = Transaction was authenticated by 3ds. If authentication was submitted to the bank, the merchant may not have chargeback protection. N =Transaction was not able to achieve 3ds authentication. If authentication was submitted to the bank, the merchant may not have chargeback protection. F = The 3ds authentication process completed but the bank response indicated that the results were invalid. The merchant will not have fraud chargeback protection.
x3dsSubmitted	This indicates if the bank request included 3ds data elements.	1 = The bank request included 3ds data elements.
(xStatus)	The ACH status that you receive in webhooks	0 (Pending) 20 (Rejected) 5 (Cancelled) 6 (Awaiting Response) 14 (Chargeback) 16 (Settled) 18 (Returned) 19 (Hold)
xIssuerResponseCode	This code received from the card association / issuer will be returned when available.

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

Card Type	Card Number
Visa	4444333322221111
Visa	4111111111111111
Mastercard	5454545454545454
Discover	6011208703331119
American Express	370276000431054
EBT	6004861944321111844
Pledger	6599973548556861
DonorsFund	6599993776775348
OJC	6900664467242419

Check (ACH)

Account Number	Routing Number
999999999	021000021 (any valid routing number)

Triggers

Declined Transaction

xName	Response
Decline	Declined

Partial Auth

(AllowPartialAuth must be set to True)

xAmount	AuthAmount
7.5	1.5
7.23	1.23

Delay/Timeout

xAmount	Behavior	Response
7.31	Response delayed 30 seconds	Try Again
7.32	Response delayed 30 seconds	Try Again
7.29	Response delayed 30 seconds	Approved

xDescription	Behavior	Response
Delay	Response delayed 30 seconds	Approved
Timeout	Response delayed 30 seconds	Try Again
Timeout_Extended	Response delayed 120 seconds	Try Again

CVV Responses

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

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

Alternative AVS Responses

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.