Choose a topic...
Please see Recurring V2 API or Reporting API for further API documentation.
Overview
The Cardknox API enables developers to process transactions via the Cardknox gateway. The API uses simple commands to make integrating with Cardknox a seamless experience.
Cardknox uses the same url for both sandbox and live accounts and they are differentiated only by the authentication key that is used. Cardknox calls this xKey. Request a sandbox account.
The API supports Credit Card, Check (ACH), EBT, Gift Card and Fraud Protection transactions. A web-based portal is available to search transactions, run reports, as well as other account features.
Cardknox also offers emulators for many popular gateways. Emulation enables developers to simply change the endpoint URL for systems currently integrated with 3rd-party gateways and use the existing commands supplied by those gateways, without the need for additional programming. Request an emulation account.
iFields
Cardknox’s iFields offers a secure solution for the client-side application, which significantly simplifies the PCI burden. It does so by hosting the sensitive payment fields (via iframes) so the cardholders’ sensitive payment information goes directly to our PCI DSS validated servers, while allowing you to retain full control of the look and feel of the payment flow. Using our iFields solution in conjunction with our API will allow you full flexibility while staying out of PCI scope. Click here to learn more about iFields.
Credentials
When you sign up for a Cardknox account, you will receive a sandbox xKey which is used to identify your account and enable you to perform test transactions. A separate xKey will be sent for your live account.
When sending a transaction, your Cardknox credentials xKey, name of your software xSoftwareName, version of your software xSoftwareVersion and Cardknox API version xVersion is required on each request.
Endpoints
Below are the endpoints URLs to send transactions to Cardknox:
URL: https://x1.cardknox.com/gateway
Alternate URL: https://b1.cardknox.com/gateway
We now support both JSON and XML via the following URLs:
JSON: https://x1.cardknox.com/gatewayjson
XML: https://x1.cardknox.com/gatewayxml
Cardknox Gateway Emulators
Authorize.net (AIM)
Endpoint URL: https://x1.cardknox.com/authorize
In order to use our authorize.net emulator, set the endpoint URL to https://x1.cardknox.com/authorize Use your Cardknox key as the login ID and transaction key.
API Login ID: (First half of Cardknox key) Transaction Key: (Second half of Cardknox key) Please note: we only emulate the AIM method.
Split Your Key:
Cardknox Key:
API Login ID:
Transaction Key:
USAePay
Endpoint URL: https://x1.cardknox.com/gate
In order to use our USAePay emulator, set the endpoint URL to https://x1.cardknox.com/gate Use your Cardknox key as the UMkey.
Request Method
Method:POST
Cardknox Gateway requires POST method to be used for enhanced security. We do not support the GET method.
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 token.
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.
To generate a token for a payment method without processing a transaction, use the save command. For credit card transaction cc:save. For check transactions, check:save.
The documentation below indicates which transaction types support tokenization.
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.
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 | Transaction status | A E D |
||||||||||||||||||
| xStatus | Result verbiage | Approved Error Declined |
||||||||||||||||||
| xError | 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 |
||||||||||||||||||
| 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 | Authorization code, approved transactions only | |||||||||||||||||||
| xBatch | Batch into which transaction will settle | |||||||||||||||||||
| xAvsResultCode | 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
|
||||||||||||||||||
| xAvsResult | AVS verbiage | See AVS result code | ||||||||||||||||||
| xCvvResultCode | 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 | |||||||||||||||||||
| xToken | Token returned for use with future transaction. | |||||||||||||||||||
| xEntryMethod | Transaction Method | Keyed EMV Swipe |
||||||||||||||||||
| 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. |
Sandbox Account Test Cases
Test Cards
Credit Card
Use these test cards to bypass the $10 limit on sandbox accounts.
| Card Type | Card Number |
|---|---|
| Visa | 4444333322221111 |
| Visa | 4111111111111111 |
| Mastercard | 5454545454545454 |
| Discover | 6011208703331119 |
| American Express | 370276000431054 |
Check (ACH)
| Routing Number | Account Number |
|---|---|
| 123456789 | 999999999 |
Triggers
Declined Transaction
| xName | Response |
|---|---|
| Decline | Declined |
Partial Auth
(xAllowPartialAuth must be set to True)
| xAmount | AuthAmount |
|---|---|
| 7.5 | 1.5 |
| 7.23 | 1.23 |
Delay/Timeout
| 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.
CREDIT CARD
Sale
xCommand = cc:Sale
The Sale command is a combination of an authorization and capture and intended when fulfilling an order right away. For transactions that are not fulfilled right away, use the authonly command initially and use the capture command to complete the sale.
The card to be charged can be communicated with 4 different approaches: xCardNum + xExp OR xMagstripe OR xToken OR SUT. Only one of these combinations can be used. Depending on a software or website’s security settings, cc:sale may also require xCVV, xStreet, or xZip and their related values.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xExp | Yes* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:sale |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 12345 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xAllowPartialAuth | No | True/False value indicating if an authorization amount is less than the initial request when full initial amount is unavailable. This variable is platform-dependent. Default is false. | True |
| xRxAmount | No | Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xDentalAmount | No | Specifies qualifying dental amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xVisionAmount | No | Specifies qualifying vision amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xTransitAmount | No | Specifies qualifying transit amount for commuter card transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xCopayAmount | No | Specifies copay amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xClinicalAmount | No | Specifies qualifying clinical amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD, AUD, COP) | CAD |
AuthOnly
xCommand = cc:AuthOnly
The AuthOnly command authorizes an amount on a cardholder’s account and places a hold on the available credit for that amount, but does not submit the charge for settlement. AuthOnly is used to reserve funds from a cardholder’s credit limit for a sale that is not ready to be processed. AuthOnly is commonly used when an order is placed on a website prior to the order being shipped or when a customer makes a hotel or car rental reservation. If the authorization amount exceeds the cardholder’s available credit, a rejected response will be returned. When successful, the authorization number is returned as RefNum and can be used to reference the authorization for a follow-up transaction. The funds will remain held until the authorization is either captured, voided, or expires. To settle an AuthOnly transaction and complete the sale, use the capture command. If an AuthOnly transaction is captured after 24 hours, it may be subject to a higher processing rate by the acquiring bank.
An AuthOnly hold only reduces the cardholder’s credit limit, but will not appear as a charge on their account. If the authorization will not be converted to a charge, Void Release can be used to release the hold prior to the expiration. The expiration timeframe varies by issuer, but is typically 7-30 days for credit cards and 3-5 days for debit cards.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xExp | Yes* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:authonly |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xAllowPartialAuth | No | True/False value indicating if an authorization amount is less than the initial request when full initial amount is unavailable. This variable is platform-dependent. Default is false. | True |
| xAutoRentalPickupDate | No* | Specific date for customer to pick up vehicle.
*Note: This field is required only for the auto rental industry. |
2020-08-21 |
| xAutoRentalPickupTime | No* | Specific time for customer to pick up vehicle.
*Note: This field is required only for the auto rental industry. |
11:15:00 |
| xAutoRentalReturnDate | No* | Specific date for customer to return vehicle.
*Note: This field is required only for the auto rental industry. |
2020-08-21 |
| xAutoRentalReturnTime | No* | Specific time for customer to return vehicle.
*Note: This field is required only for the auto rental industry. |
11:15:00 |
| xRxAmount | No | Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xDentalAmount | No | Specifies qualifying dental amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xVisionAmount | No | Specifies qualifying vision amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xTransitAmount | No | Specifies qualifying transit amount for commuter card transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xCopayAmount | No | Specifies copay amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xClinicalAmount | No | Specifies qualifying clinical amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD) | CAD |
Capture
xCommand = cc:Capture
The Capture command is used to settle funds from a previous authorization and withdraw the funds from the cardholder’s account. The RefNumber from related authorization is required when submitting a Capture request. To perform an authorization and capture in the same command, use the Sale command.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:capture |
| xAmount | No | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
Adjust
xCommand = cc:Adjust
You can use the Adjust command to update certain fields on a transaction, such as xOrderID. This action will not reprocess the transaction, but will only update the information. However, you can only update the xAmount, xTax, and xTip fields on an authorization before it is captured; you cannot change these fields on a transaction that was already processed.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:adjust |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xCustom01 – xCustom03 | No | Custom fields available for custom data such as customer comments, etc. | Register01 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xRefNum | Yes*
The xRefNum from the related authorization is required when submitting an Adjust transaction. |
Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) |
81234568 |
| xName | No | The cardholder’s name. | John Doe |
| xDescription | No | Additional data optionally passed along for reporting. | Transaction description |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xSignature | No | The Base 64 encoded customer signature. | |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
Save
xCommand = cc:Save
The Save command is used to send account information and request a token from Cardknox, but does not submit the transaction for processing. The response returns a token which references that account information. A token at a minimum references the credit card number, but if other data is sent, such as billing address, that will be associated with the token as well.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xExp | Yes* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:save |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
PostAuth
xCommand = cc:PostAuth
Some authorizations will require a voice authorization before they can be approved. When a verbal authorization is issued by the bank, that number can be sent with the PostAuth command to verify the authorization.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xExp | Yes* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:postauth |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xAuthCode | Yes | xAuthCode is a verificaton number provided by the issuing bank to be used with the cc:postauth command. | T4321A |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xAllowPartialAuth | No | True/False value indicating if an authorization amount is less than the initial request when full initial amount is unavailable. This variable is platform-dependent. Default is false. | True |
| xRxAmount | No | Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xDentalAmount | No | Specifies qualifying dental amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xVisionAmount | No | Specifies qualifying vision amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xTransitAmount | No | Specifies qualifying transit amount for commuter card transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xCopayAmount | No | Specifies copay amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xClinicalAmount | No | Specifies qualifying clinical amount for FSA transactions. xAllowPartialAuth must be set to True. | 1.50 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD) | CAD |
Credit
xCommand = cc:Credit
The Credit command refunds money from a merchant to a cardholder’s card that is not linked to any previous transaction.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xExp | Yes* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:credit |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD) | CAD |
Refund
xCommand = cc:Refund
The Refund command is used to refund a full or partial amount of a previous transaction using xRefNum. Partial check refunds aren’t currently supported.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:refund |
| xAmount | Yes | Refund amount. Can be equal or less than original transaction. | 9.99 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
Void Refund
xCommand = cc:VoidRefund
The VoidRefund command will either void the pending transaction if it has not settled yet, or it will fully refund the transaction if it has already settled.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:voidrefund |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
Void Release
xCommand = cc:VoidRelease
The Void Release command releases a pending authorization amount back to the cardholder’s credit limit without waiting for the standard authorization timeframe to expire.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:voidrelease |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
Void
xCommand = cc:Void
The Void command voids a transaction that has not yet settled using xRefNum.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | cc:void |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
CHECK (ACH)
Sale
xCommand = check:Sale
The Check Sale command debits funds from a customer’s checking or savings account using one of the following options:
- xAccount and xRouting parameters
- xCheckImageFront, xCheckImageRear, and xMICR parameters
The merchant must have a supported Check/ACH processing account to use either of these options.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | check:sale |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRouting | Yes* | The check ABA Routing number. | 021202337 |
| xAccount | Yes* | The check Account number. | 1234567890 |
| xName | Yes | Name on account | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xMICR | No | The routing, account and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner. | t021000021t 123456789o _2542 |
| xCheckNum | No | The Check number. | 999 |
| xCheckImageFront | No | The front image of the check, in Base 64 encoded image format. | data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/wAARCAABAAEDAREAAhEBAxEB/8QAFAABAAAAAAAAAAAAAAAAAAAACP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AVIP/2Q== |
| xCheckImageRear | No | The back image of the check, in Base 64 encoded image format. | data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/wAARCAABAAEDAREAAhEBAxEB/8QAFAABAAAAAAAAAAAAAAAAAAAACP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AVIP/2Q== |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD) | CAD |
Credit
xCommand = check:Credit
The Credit command sends money from a merchant to a customer’s bank account that is not linked to any previous transaction. With check transactions, this is commonly used for paying third parties such as paying vendors. To refund a previous check sale, use Check:Refund instead.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | check:credit |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRouting | Yes* | The check ABA Routing number. | 021202337 |
| xAccount | Yes* | The check Account number. | 1234567890 |
| xName | Yes | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xMICR | No | The routing, account and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner. | t021000021t 123456789o _2542 |
| xCheckNum | No | The Check number. | 999 |
| xCheckImageFront | No | The front image of the check, in Base 64 encoded image format. | data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/wAARCAABAAEDAREAAhEBAxEB/8QAFAABAAAAAAAAAAAAAAAAAAAACP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AVIP/2Q== |
| xCheckImageRear | No | The back image of the check, in Base 64 encoded image format. | data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/wAARCAABAAEDAREAAhEBAxEB/8QAFAABAAAAAAAAAAAAAAAAAAAACP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAwDAQACEQMRAD8AVIP/2Q== |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
| xCurrency | No | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (supported currencies are: USD, GBP, ILS, EUR, MXN, CAD) | CAD |
Save
xCommand = check:Save
The Save command is used to send account information and request a token from Cardknox, but does not submit the transaction for processing. The response returns a token which references that account information. A token at a minimum references the account and routing number, but if other data is sent, such as billing address, that will be associated with the token as well.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | check:save |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRouting | Yes* | The check ABA Routing number. | 021202337 |
| xAccount | Yes* | The check Account number. | 1234567890 |
| xName | Yes | The cardholder’s name. | John Doe |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xMICR | No | The routing, account and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner. | t021000021t 123456789o _2542 |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Void
xCommand = check:Void
The Void command voids a check transaction that is pending being sent to the bank, typically at the end of each day.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | check:void |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
Refund
xCommand = check:Refund
The Refund command is used to refund a full refund of a previous settled check transaction, using xRefNum. Partial check refund isn’t supported.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | check:refund |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
EBT Food Stamp
Sale
xCommand = ebtfs:sale
The Sale command is used to make a purchase on an EBT cardholder’s food stamp account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtfs:sale |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
| xCustReceipt | No | True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details. | False |
Credit
xCommand = ebtfs:credit
The Credit command is used to credit to an EBT cardholder’s food stamp account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtfs:credit |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Balance
xCommand = ebtfs:balance
The Balance command is used to check the balance on an EBT food stamp card.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtfs:balance |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
Voucher
xCommand = ebtfs:voucher
The Voucher command is used to process manual EBT food stamp voucher.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtfs:voucher |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xVoucherApproval | Yes | The EBT voucher approval code. | 123df1248f |
| xVoucherSerial | Yes | The EBT voucher serial number. | 123 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
EBT Cash Benefits
Sale
xCommand = ebtcb:sale
The Sale command is used to make a purchase on an EBT cardholder’s cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtcb:sale |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Cash
xCommand = ebtcb:Cash
The Cash command enables a cash withdrawal from on an EBT cardholder’s cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtcb:cash |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Balance
xCommand = ebtcb:Balance
The Balance command is used to check the balance on an EBT cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtcb:balance |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
EBT Wic (eWic)
Sale
xCommand = ebtw:sale
The Sale command is used to make a purchase on an EBTW cardholder’s cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtw:sale |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| x1UnitPrice | Yes | Unit price for item specified in xUPC. Additional items can be specified by incrementing (i.e x2UnitPrice, x3UnitPrice, etc.) | 2.5 |
| x1Qty | Yes | Quantity of item specified in xUPC. Additional items can be specified by incrementing (i.e x2Qty, x3Qty, etc.) | 2 |
| x1Upc | Yes | Universal Product Code. Additional items can be specified by incrementing (i.e x2Upc, x3Upc, etc.) | 075457026002 |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of an eWIC card. When using xMagstripe, xCardNum and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Balance
xCommand = ebtw:Balance
The Balance command is used to check the balance on an EBTW cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtw:balance |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xMagstripe | No* | The magstripe data of an eWIC card. When using xMagstripe, xCardNum and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
Void
xCommand = ebtw:Void
The Void command voids a purchase made with an EBTW cardholder’s cash benefit account.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.5 | 4.5.5 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | ebtw:void |
| xDUKPT | Yes | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xRefNum | Yes | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
GIFT CARD
Issue
xCommand = gift:issue
The Issue command is used to issue funds to a Cardknox gift card.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | Gift card number. *Alternatively, xMagstripe or xToken can be used. | 4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | gift:issue |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used card. When using this variable, xCardNum,and xMagstripe should not be used. (Max 50 Alphanumeric Characters) | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xExp | No | Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. *Required and available only when xCardNum is used. | 1249 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Redeem
xCommand = gift:redeem
The Redeem command is used to debit funds from a Cardknox gift card.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | Gift card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | gift:redeem |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xToken | No* | The Cardknox token that references a previously used card. When using this variable, xCardNum,and xMagstripe should not be used. (Max 50 Alphanumeric Characters) | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xExp | No | Gift card expiration number. Format: MMYY. For sandbox accounts, use any date in the future. *Required and available only when xCardNum is used. | 1249 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Balance
xCommand = gift:balance
The Balance command is used to check the available balance on a Cardknox gift card.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | gift:balance |
| xToken | No* | The Cardknox token that references a previously used payment method. When using a token, xCardNum, xExp and xMagstripe should not be used. | 61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84 |
| xExp | No* | The card expiration number. Format: MMYY. For sandbox test transactions, use any date in the future. *xExp is required when sending in xCardnum and cannot be used with xMagstripe | 1249 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xCVV | No | 3-digit code from the back of the card (4-digit code from the front of the card for Amex). | 123 |
| xStreet | No | The billing street address of the cardholder. | 123 Any Street |
| xZip | No | The billing zip code of the cardholder. | 11111 |
| xMagstripe | No* | The magstripe data of a credit card. Magstripe data includes the card number and expiration date. When using this command, xCardNum, xExp and xToken should not be used. Encrypted Card data can also be sent using xMagstripe. | %B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789? |
| xName | No | The cardholder’s name. | John Doe |
| xAuthCode | No | xAuthCode is a verificaton number provided by the issuing bank to be used with the cc:postauth command. | T4321A |
| xCardpresent | No | Yes, No. For use in retail environments to indicate if the card is present. | No |
| xDUKPT | No | The DUK/PT key for PIN Debit and EBT transactions.The first 16 characters are the encrypted pin block, followed by the 6 character long Key Set Identifier (KSID). The remaining characters are the PIN Pad serial number and transaction counter. | |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xRefNum | No | Used to reference a previous transaction when doing a follow-up transaction, typically a refund, void, or capture. (Note: xRefnum can be a 64-bit number and should be stored as BIGINT, Long, Int64 or String) | 81234568 |
| xInvoice | No | The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling. | 123456A |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xIP | No | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | No | The customer’s email address. | test@example.com |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillFirstName | No | The customer’s first name for their billing profile. | John |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillLastName | No | The customer’s last/family name for their billing profile. | Doe |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet | No | The customer’s street address for their billing profile. | 123 Any Street |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCity | No | The customer’s city for their billing profile. | Anytown |
| xBillState | No | The customer’s state for their billing profile. | NY |
| xBillZip | No | The customer’s zip code for their billing profile. | 11111 |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillPhone | No | The customer’s phone number for their billing profile. | 8005551212 |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipFirstName | No | The customer’s first name for their shipping profile. | John |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipLastName | No | The customer’s last/family name for their shipping profile. | Doe |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet | No | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCity | No | The customer’s city for their shipping profile. | Anytown |
| xShipState | No | The customer’s state for their shipping profile. | NY |
| xShipZip | No | The customer’s zip code for their shipping profile. | 11111 |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipPhone | No | The customer’s phone number for their shipping profile. | 8005551212 |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xMICR | No | The routing, account and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner. | t021000021t 123456789o _2542 |
| xRouting | No | The check ABA Routing number. | 021202337 |
| xGatewayRefNum | No | Transaction RefNum received from Gateway for FraudWatch verification. | 852585258 |
| xGatewayResult | No | Transaction status received from gateway for FraudWatch verification. (Approved/Declined/Error) | Approved |
| xGatewayError | No | Transaction RefNum received from Gateway for FraudWatch verification. | 845455484 |
| xGatewayCVV | No | CVV for for FraudWatch verification. | M |
| xGatewayAVS | No | Street Address for FraudWatch verification. | YYY |
| xOrderType | No | Specifies if the order origin is Internet OR Phone for FraudWatch verification. | Internet |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xExistingCustomer | No | Yes/No value indicating if customer is a repeat customer. | No |
| xOrderItems | No | Summary of products ordered. | Sony Digital Camera |
| xCustomerComments | No | Comments submitted by customer along with order. | Please ship as soon as possible |
| xShipMethod | No | The shipping carrier/service used. | UPS Ground |
| xShipAmount | No | The total cost of shipping charges. | 29.99 |
| xShipEmail | No | The ShipTo email address. | example@example.com |
| xAllowDuplicate | No | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. | True |
Activate
xCommand = gift:activate
The Activate command is used to activate a Cardknox gift card.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | gift:balance |
Deactivate
xCommand = gift:deactivate
The Deactivate command is used to deactivate a Cardknox gift card.(Note: you can still check the balance of the gift card even after it has been deactivated.)
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | The customer card number. *Alternatively, xToken, xMagStripe or SUT can be used. |
4444333322221111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | gift:balance |
FRAUD
Fraud Submit
xCommand = fraud:submit
The Submit command is used in conjunction with a valid FraudWatch account to submit ecommerce transactions for a fraud verification check.
| Variable | Required | Description | Sample Data |
|---|---|---|---|
| xCardNum | Yes* | Masked Card number with BIN and last 4 digits exposed | 444433xxxxxx1111 |
| xKey | Yes | Your Cardknox API Key. | [xkeycredentials] |
| xVersion | Yes | Gateway API Version. The current version is 4.5.8 | 4.5.8 |
| xSoftwareName | Yes | Name of your software. | [xsoftwarecredentials] |
| xSoftwareVersion | Yes | Version number of your software. | [xversioncredentials] |
| xCommand | Yes | Cardknox transaction type. | fraud:submit |
| xAmount | Yes | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. | 9.99 |
| xCustom01 | No | 20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20. | Register01 |
| xInvoice | Yes | Invoice number | 123456A |
| xIP | Yes | The customer’s IP address. Typically used for fraud detection. | 1.1.1.1 |
| xEmail | Yes | Customer billing email. | test@example.com |
| xBillFirstName | Yes | The customer’s first name for their billing profile. | John |
| xBillLastName | Yes | The customer’s last/family name for their billing profile. | Doe |
| xBillStreet | Yes | The customer’s street address for their billing profile. | 123 Any Street |
| xBillCity | Yes | The customer’s city for their billing profile. | Anytown |
| xBillState | Yes | The customer’s state for their billing profile. | NY |
| xBillZip | Yes | The customer’s zip code for their billing profile. | 11111 |
| xBillPhone | Yes | The customer’s phone number for their billing profile. | 8005551212 |
| xShipFirstName | Yes | The customer’s first name for their shipping profile. | John |
| xShipLastName | Yes | The customer’s last/family name for their shipping profile. | Doe |
| xShipStreet | Yes | The customer’s street address for their shipping profile. | 123 Any Street |
| xShipCity | Yes | The customer’s city for their shipping profile. | Anytown |
| xShipState | Yes | The customer’s state for their shipping profile. | NY |
| xShipZip | Yes | The customer’s zip code for their shipping profile. | 11111 |
| xShipPhone | Yes | The customer’s phone number for their shipping profile. | 8005551212 |
| xGatewayRefNum | Yes | Transaction RefNum received from Gateway for FraudWatch verification. | 852585258 |
| xGatewayResult | Yes | Transaction status received from gateway for FraudWatch verification. (Approved/Declined/Error) | Approved |
| xGatewayCVV | Yes | CVV for for FraudWatch verification. | M |
| xGatewayAVS | Yes | Street Address for FraudWatch verification. | YYY |
| xOrderType | Yes | Specifies if the order origin is Internet OR Phone for FraudWatch verification. | Internet |
| xExistingCustomer | Yes | Yes/No value indicating if customer is a repeat customer. | No |
| xShipEmail | Yes | The ShipTo email address. | example@example.com |
| xName | No | The cardholder’s name. | John Doe |
| xTax | No | The tax portion that is included in the total transaction amount (xAmount). | .05 |
| xTip | No | The tip portion that is included in the total transaction amount (xAmount). | .05 |
| xPONum | No | The merchant’s purchase order number for the transaction. | 123485B |
| xComments | No | Additional data optionally passed along to the receipt. | This is a comment |
| xDescription | No | Additional data optionally passed along for reporting. | This is a description |
| xFax | No | The customer’s fax number. | 8885551212 |
| xBillMiddleName | No | The customer’s middle name or initial for their billing profile. | Max |
| xBillCompany | No | The customer’s company name for their billing profile. | Acme |
| xBillStreet2 | No | The customer’s street address 2nd line for their billing profile. | Apt 4b |
| xBillCountry | No | The customer’s Country for their billing profile. | USA |
| xBillMobile | No | The customer’s mobile number for their billing profile. | 8005551111 |
| xShipMiddleName | No | The customer’s middle name or initial for their shipping profile. | Max |
| xShipCompany | No | The customer’s company name for their shipping profile. | Acme |
| xShipStreet2 | No | The customer’s street address 2nd line for their shipping profile. | Apt 4b |
| xShipCountry | No | The customer’s Country for their shipping profile. | USA |
| xShipMobile | No | The customer’s mobile number for their shipping profile. | 8005551111 |
| xGatewayError | No | Transaction RefNum received from Gateway for FraudWatch verification. | 845455484 |
| xOrderID | No | Unique Order Number for FraudWatch verification. | 12356 |
| xOrderItems | No | Summary of products ordered. | Sony Digital Camera |
| xCustomerComments | No | Comments submitted by customer along with order. | Please ship as soon as possible |
| xShipMethod | No | The shipping carrier/service used. | UPS Ground |
| xShipAmount | No | The total cost of shipping charges. | 29.99 |
Please see Recurring V2 API or Reporting API for further API documentation.
