Credit Card

Overview

This page contains all API documentation for Credit Card (CC) transactions. For more information regarding account access, navigate to the Transaction API parent page.

How to Generate Cardknox Keys

1. Sign in to the Cardknox Merchant Portal.

2. Select "Account Settings" from the navigation bar.

3. Select "Keys" from the sub-menu.

4. Click "Create a Key" in the top-right corner.

5. Choose the desired key type (API or iFields), description (software, etc.), and permissions.

6. Click "Create and View" and copy your key.

It is critical to copy your key and save it in a secure location, as you won’t be able to obtain the key again.

Endpoints

Health Check

HTTP Request Method: GET

https://x1.cardknox.com/status

Transactions

HTTP Request Method: POST

Cardknox allows you to send the data in FormData, JSON, and XML formats.

Add to the base URL any of the following formats to indicate which format you are sending it as:

FormData	/gatewayform	https://x1.cardknox.com/gatewayform
JSON	/gatewayjson	https://x1.cardknox.com/gatewayjson
XML	/gatewayxml	https://x1.cardknox.com/gatewayxml

Transactions

Sale

POST cc:sale

xCommand = cc:Sale

The Sale command is a combination of the authorization and capture transactions. it is intended for use when fulfilling an order right away. For transactions that are not fulfilled right away, use the authonly command initially and then 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 the software or website’s security settings, cc:sale may also require xCVV, xStreet, or xZip and their related values.

Request Body

Name	Type	Description
xExp*	String	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.
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API Version. The current version is 5.0.0.
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount*	String	The total amount of the transaction, inclusive of tax and tip if applicable.
xToken	String	The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.
xCustom01	String	20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20
xCVV	String	3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xMagstripe	String	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.
xName	String	The cardholder’s name.
xDUKPT	String	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	String	The tax portion that is included in the total transaction amount (xAmount)
xTip	String	The tip portion that is included in the total transaction amount (xAmount).
xInvoice	String	The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPONum	String	The merchant’s purchase order number for the transaction
xComments	String	Additional data that is optionally passed along to the receipt.
xDescription	String	Additional data that is optionally passed along for reporting
xIP	String	The customer’s IP address. Typically used for fraud detection.
xEmail	String	The customer’s email address
xFax	String	The customer’s fax number
xBillFirstName	String	The customer’s first name for their billing profile
xBillMiddleName	String	The customer’s middle name or initial for their billing profile
xBillLastName	String	The customer’s last/family name for their billing profile
xBillCompany	String	The customer’s company name for their billing profile
xBillStreet	String	The customer’s street address for their billing profile
xBillStreet2	String	The customer’s street address 2nd line for their billing profile
xBillCity	String	The customer’s city for their billing profile.
xBillState	String	The customer’s state for their billing profile
xBillZip	String	The customer’s zip code for their billing profile
xBillCountry	String	The customer’s country for their billing profile
xBillPhone	String	The customer’s phone number for their billing profile
xBillMobile	String	The customer’s mobile number for their billing profile
xShipFirstName	String	The customer’s first name for their shipping profile
xShipMiddleName	String	The customer’s middle name or initial for their shipping profile
xShipLastName	String	The customer’s last/family name for their shipping profile
xShipCompany	String	The customer’s company name for their shipping profile
xShipStreet	String	The customer’s street address for their shipping profile
xShipStreet2	String	The customer’s street address 2nd line for their shipping profile
xShipCity	String	The customer’s city for their shipping profile
xShipState	String	The customer’s state for their shipping profile
xShipZip	String	The customer’s zip code for their shipping profile
xShipCountry	String	The customer’s country for their shipping profile
xShipPhone	String	The customer’s phone number for their shipping profile
xShipMobile	String	The customer’s mobile number for their shipping profile
xHotelCheckInDate	String	The customer’s date of hotel check-in
xHotelCheckOutDate	String	The customer's date of hotel check-out
xAllowPartialAuth	String	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.
xRxAmount	String	Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True.
xDentalAmount	String	Specifies qualifying dental amount for FSA transactions. xAllowPartialAuth must be set to True.
xVisionAmount	String	Specifies qualifying vision amount for FSA transactions. xAllowPartialAuth must be set to True.
xTransitAmount	String	Specifies qualifying transit amount for commuter card transactions. xAllowPartialAuth must be set to True.
xCopayAmount	String	Specifies Co-pay amount for FSA transactions. xAllowPartialAuth must be set to True.
xClinicalAmount	String	Specifies qualifying clinical amount for FSA transactions. xAllowPartialAuth must be set to True.
xOrderId	String	Unique order number for FraudWatch verification
xExistingCustomer	String	Yes/No value indicating if customer is a repeat customer
xAllowDuplicate	String	By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xCustReceipt	String	True/False value indicating if the email address specified in xemail should receive a receipt containing the transaction details.
xCurrency	String	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 (see list of all supported currencies).
xReturnPaymentID	Boolean	True/False value indicating if the user would like to receive xPaymentId in the transaction response. Unless specified, the value is “False”. Unlike an xToken which will return a new value on transactions of the same card, xPaymentId will return the same value for transactions using the same card.
xSplitFee	String	The amount that should be sent to the Split Fee account Example: xAmount = 100 xSplitFee = 10 90 Will go to the xKey account and 10 will go to the Split Fee account (Split Fee account is set in the Cardknox gateway backend) Note: To use this feature, the account needs to be setup to support it. Otherwise, an error will be returned.
xTimeoutSeconds	String	Configurable amount of seconds in which the request will wait for a response.
xVendorId	String	The parameter that tells the gateway which developer is performing the transaction. If the value matches the account of the iFields key, the gateway will allow the transaction to work even though the API and iFields keys are from different accounts. See more here
xCardNum*	String	The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.
xDigitalWalletType	String	This field should indicate the wallet type in a case where the card number is a digital wallet token (Ex: "Google Pay")

200: OK

For a full list of response codes, see the table in the Introduction page.

{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"601518451",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"11295A",
"xBatch":"11948741",
"xAvsResultCode":"NNN",
"xAvsResult":"Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"M",
"xCvvResult":"Match",
"xAuthAmount":"35.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xToken":"8n21126mq0hn253p9m7964p5qn60000g",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"3/3/2022 7:36:34 AM",
"xEntryMethod":"Keyed",
"xReviewed":"N"
}

Sale - Request Payload Example

{
    "xCardNum": "4444333322221111",
    "xExp": "1030",
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:sale",
    "xAmount": "35.00",
    "xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
    "xCustom01": "Register01",
    "xCVV": "123",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
    "xName": "John Doe",
    "xDUPKT": "Example",
    "xDigitalWalletType": "Google Pay",
    "xTax": "2.00",
    "xTip": "2.00",
    "xInvoice": "123456A",
    "xPONum": "123456B",
    "xComments": "This is a comment",
    "xDescription": "This is a description",
    "xIP": "1.2.3.4",
    "xEmail": "[e-mail]",
    "xFax": "1234567890",
    "xBillFirstName": "John",
    "xBillMiddleName": "Max",
    "xBillLastName": "Doe",
    "xBillCompany": "Acme", 
    "xBillStreet": "123 Any Street", 
    "xBillStreet2": "Apt 4b", 
    "xBillCity": "Anytown", 
    "xBillState": "NY", 
    "xBillZip": "12345", 
    "xBillCountry": "USA", 
    "xBillPhone": "8005551212", 
    "xBillMobile": "8005551111", 
    "xShipFirstName": "John", 
    "xShipMiddleName": "Max", 
    "xShipLastName": "Doe", 
    "xShipCompany": "Acme", 
    "xShipStreet": "123 Any Street", 
    "xShipStreet2": "Apt 4b", 
    "xShipCity": "Anytown", 
    "xShipState": "NY", 
    "xShipZip": "11111", 
    "xShipCountry": "USA", 
    "xShipPhone": "8005551212", 
    "xShipMobile": "8005551111",
    "xHotelCheckInDate": "7/1/2024",
    "xHotelCheckOutDate": "7/10/2024",
    "xAllowPartialAuth": "TRUE",
    "xRxAmount": "1.50",
    "xDentalAmount": "1.50",
    "xVisionAmount": "1.50",
    "xTransitAmount": "1.50",
    "xCopayAmount": "1.50",
    "xClinicalAmount": "1.50",
    "xOrderID": "12356",
    "xExistingCustomer": "TRUE",
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "TRUE",
    "xCurrency": "USD",
    "xTimeoutSeconds": "10",
    "xVendorId": "12345"
}

AuthOnly

POST cc: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; it 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 the issuer, but is typically 7-30 days for credit cards and 3-5 days for debit cards.

Request Body

Name	Type	Description
xCardNum*	String	The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.
xExp*	String	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.
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount*	String	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
xToken	String	The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.
xCustom01	String	20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20.
xCVV	String	3-digit code from the back of the card (4-digit code from the front of the card for Amex)
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xMagstripe	String	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.
xName	String	The cardholder’s name
xDUKPT	String	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	String	The tax portion that is included in the total transaction amount (xAmount)
xTip	String	The tip portion that is included in the total transaction amount (xAmount)
xInvoice	String	The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPONum	String	The merchant’s purchase order number for the transaction
xComments	String	Additional data optionally passed along to the receipt
xDescription	String	Additional data optionally passed along for reporting
xIP	String	The customer’s IP address. Typically used for fraud detection.
xEmail	String	The customer’s email address
xBillLastName	String	The customer’s last/family name for their billing profile
xBillMiddleName	String	The customer’s middle name or initial for their billing profile
xBillFirstName	String	The customer’s first name for their billing profile
xFax	String	The customer’s fax number
xBillCompany	String	The customer’s company name for their billing profile.
xBillStreet	String	The customer’s street address for their billing profile.
xBillStreet2	String	The customer’s street address 2nd line for their billing profile
xBillCity	String	The customer’s city for their billing profile
xBillState	String	The customer’s state for their billing profile
xBillZip	String	The customer’s zip code for their billing profile
xBillCountry	String	The customer’s country for their billing profile
xBillPhone	String	The customer’s phone number for their billing profile
xBillMobile	String	The customer’s mobile number for their billing profile
xShipFirstName	String	The customer’s first name for their shipping profile
xShipMiddleName	String	The customer’s middle name or initial for their shipping profile
xShipLastName	String	The customer’s last/family name for their shipping profile
xShipCountry	String	The customer’s company name for their shipping profile
xShipStreet	String	The customer’s street address for their shipping profile
xShipStreet2	String	The customer’s street address 2nd line for their shipping profile
xShipCity	String	The customer’s city for their shipping profile
xShipState	String	The customer’s state for their shipping profile
xShipZip	String	The customer’s zip code for their shipping profile
xShipCountry	String	The customer’s country for their shipping profile.
xShipPhone	String	The customer’s phone number for their shipping profile
xShipMobile	String	The customer’s mobile number for their shipping profile
xHotelCheckInDate	String	The customer’s date of hotel check-in.
xHotelCheckOutDate	String	The customer’s date of hotel check-out.
xAllowPartialAuth	String	True/False value indicating if an authorization amount is less than the initial request when the full initial amount is unavailable. This variable is platform-dependent. Default is false.
xAutoRentalPickupDate	String	Specific date for customer to pick up vehicle. *Note: This field is required only for the auto rental industry.
xAutoRentalPickupTime	String	Specific time for customer to pick up vehicle. *Note: This field is required only for the auto rental industry.
xAutoRentalReturnDate	String	Specific date for customer to return vehicle. *Note: This field is required only for the auto rental industry.
xAutoRentalReturnTime	String	Specific time for customer to return vehicle. *Note: This field is required only for the auto rental industry.
xRxAmount	String	Specifies qualifying prescription amount for FSA transactions. xAllowPartialAuth must be set to True.
xDentalAmount	String	Specifies qualifying dental amount for FSA transactions. xAllowPartialAuth must be set to True.
xVisionAmount	String	Specifies qualifying vision amount for FSA transactions. xAllowPartialAuth must be set to True.
xTransitAmount	String	Specifies qualifying transit amount for commuter card transactions. xAllowPartialAuth must be set to True.
xCopayAmount	String	Specifies Co-pay amount for FSA transactions. xAllowPartialAuth must be set to True.
xClinicalAmount	String	Specifies qualifying clinical amount for FSA transactions. xAllowPartialAuth must be set to True.
xOrderID	String	Unique order number for FraudWatch verification.
xAllowDuplicate	String	By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xCustReceipt	String	True/False value indicating if the email address specificied in xemail should receive a receipt containing the transaction details.
xCurrency	String	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. (see list of all supported currencies).
xTimeoutSeconds	String	Configurable amount of seconds in which the request will wait for a response.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

For a full list of response codes, see the table in the Introduction page.

{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"601519890",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"47436A",
"xAvsResultCode":"NNN",
"xAvsResult":"Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"M",
"xCvvResult":"Match",
"xAuthAmount":"35.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xName":"John Doe",
"xToken":"q3nq31h6n8n24623n9qg695hhgh24g61",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"3/3/2022 7:43:21 AM",
"xIsSplitCapturable":"1",
"xEntryMethod":"Keyed",
"xReviewed":"N"
}

AuthOnly - Request Payload Example

{
    "xCardNum": "4444333322221111",
    "xExp": "1030",
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:authonly",
    "xAmount": "35.00",
    "token": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
    "xCustom01": "Register01",
    "xCVV": "123",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
    "xName": "John Doe",
    "xDUPKT": 
    "xTax": "2.00",
    "xTip": "2.00",
    "xInvoice": "123456A",
    "xPONum": "123456B",
    "xComments": "This is a comment",
    "xDescription": "This is a description",
    "xIP": "1.2.3.4",
    "xEmail": "[e-mail]",
    "xFax": "1234567890",
    "xBillFirstName": "John",
    "xBillMiddleName": "Max",
    "xBillLastName": "Doe",
    "xBillCompany": "Acme", 
    "xBillStreet": "123 Any Street", 
    "xBillStreet2": "Apt 4b", 
    "xBillCity": "Anytown", 
    "xBillState": "NY", 
    "xBillZip": "12345", 
    "xBillCountry": "USA", 
    "xBillPhone": "8005551212", 
    "xBillMobile": "8005551111", 
    "xShipFirstName": "John", 
    "xShipMiddleName": "Max", 
    "xShipLastName": "Doe", 
    "xShipCompany": "Acme", 
    "xShipStreet": "123 Any Street", 
    "xShipStreet2": "Apt 4b", 
    "xShipCity": "Anytown", 
    "xShipState": "NY", 
    "xShipZip": "11111", 
    "xShipCountry": "USA", 
    "xShipPhone": "8005551212", 
    "xShipMobile": "8005551111",
    "xHotelCheckInDate": "7/1/2024",
    "xHotelCheckOutDate": "7/10/2024",
    "xAllowPartialAuth": "TRUE",
    "xAutoRentalPickupDate": "2020-08-21",
    "xAutoRentalPickupTime": "11:15:00",
    "xAutoRentalReturnDate": "2020-08-21",
    "xAutoRentalReturnTime": "11:15:00",
    "xRxAmount": "1.50",
    "xDentalAmount": "1.50",
    "xVisionAmount": "1.50",
    "xTransitAmount": "1.50",
    "xCopayAmount": "1.50",
    "xClinicalAmount": "1.50",
    "xOrderID": "12356",
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "TRUE",
    "xCurrency": "USD",
    "xTimeoutSeconds": "10"
}

Capture

POST cc: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 the associated authorization is required when submitting a Capture request. To perform an authorization and capture in the same command, use the Sale command.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API Version. The current version is 5.0.0
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount	String	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
xCustom01	String	20 custom fields are available for custom data such as customer comments, etc. Use xCustom01 through xCustom20.
xStreet	String	The billing street address of the cardholder.
xZip	String	The billing zip code of the cardholder.
xRefNum*	String	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).
xName	String	The cardholder’s name
xTax	String	The tax portion that is included in the total transaction amount (xAmount)
xTip	String	The tip portion that is included in the total transaction amount (xAmount)
xInvoice	String	The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPONum	String	The merchant’s purchase order number for the transaction
xComments	String	Additional data optionally passed along to the receipt
xDescription	String	Additional data optionally passed along for reporting
xIP	String	The customer’s IP address. Typically used for fraud detection.
xEmail	String	The customer’s email address
xFax	String	The customer’s fax number
xBillFirstName	String	The customer’s first name for their billing profile
xBillMiddleName	String	The customer’s middle name for their billing profile
xBillLastName	String	The customer’s last name for their billing profile
xBillCompany	String	The customer’s company name for their billing profile
xBillStreet	String	The customer’s street address for their billing profile
xBillStreet2	String	The customer’s street address 2nd line for their billing profile
xBillCity	String	The customer’s city for their billing profile
xBillState	String	The customer’s state for their billing profile
xBillZip	String	The customer’s zip code for their billing profile
xBillCountry	String	The customer’s country for their billing profile
xBillPhone	String	The customer’s phone number for their billing profile
xBillMobile	String	The customer’s mobile number for their billing profile
xShipFirstName	String	The customer’s first name for their shipping profile
xShipMiddleName	String	The customer’s middle name for their shipping profile
xShipLastName	String	The customer’s last name for their shipping profile
xShipCompany	String	The customer’s company name for their shipping profile
xShipStreet	String	The customer’s street address for their shipping profile
xShipStreet2	String	The customer’s street address 2nd line for their shipping profile
xShipCity	String	The customer’s city for their shipping profile
xShipState	String	The customer’s state for their shipping profile
xShipZip	String	The customer’s zip code for their shipping profile
xShipCountry	String	The customer’s country for their shipping profile
xShipPhone	String	The customer’s phone number for their shipping profile
xShipMobile	String	The customer’s mobile number for their shipping profile
xAllowDuplicate	String	By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xCustReceipt	String	True/False value indicating if the email address specified in xemail should receive a receipt containing the transaction details.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

For a full list of response codes, see the table in the Introduction page.

{
"xResult":"E",
"xStatus":"Error",
"xError":"Invalid xRefNum",
"xErrorCode":"01463",
"xRefNum":"601523283",
"xInvoice":"123456",
"xDate":"3/3/2022 7:57:59 AM"
}

Capture - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:capture",
    "xAmount": "35.00",
    "xCustom01": "Register01",
    "xCVV": "123",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xRefNum": "81234568",
    "xName": "John Doe",
    "xTax": "2.00",
    "xTip": "2.00",
    "xInvoice": "123456A",
    "xPONum": "123456B",
    "xComments": "This is a comment",
    "xDescription": "This is a description",
    "xIP": "1.2.3.4",
    "xEmail": "[e-mail]",
    "xFax": "1234567890",
    "xBillFirstName": "John",
    "xBillMiddleName": "Max",
    "xBillLastName": "Doe",
    "xBillCompany": "Acme", 
    "xBillStreet": "123 Any Street", 
    "xBillStreet2": "Apt 4b", 
    "xBillCity": "Anytown", 
    "xBillState": "NY", 
    "xBillZip": "12345", 
    "xBillCountry": "USA", 
    "xBillPhone": "8005551212", 
    "xBillMobile": "8005551111", 
    "xShipFirstName": "John", 
    "xShipMiddleName": "Max", 
    "xShipLastName": "Doe", 
    "xShipCompany": "Acme", 
    "xShipStreet": "123 Any Street", 
    "xShipStreet2": "Apt 4b", 
    "xShipCity": "Anytown", 
    "xShipState": "NY", 
    "xShipZip": "11111", 
    "xShipCountry": "USA", 
    "xShipPhone": "8005551212", 
    "xShipMobile": "8005551111", 
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "TRUE"
}

Adjust

POST cc: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; it 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.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key
xVersion*	String	Gateway API Version. The current version is 5.0.0
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount*	String	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
Custom01	String	Custom fields available for custom data such as customer comments, etc.
Custom02	String	Custom fields available for custom data such as customer comments, etc.
Custom03	String	Custom fields available for custom data such as customer comments, etc.
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xRefNum*	String	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).
xName	String	The cardholder’s name
xDescription	String	Additional data optionally passed along for reporting
xOrderID	String	Unique Order Number for FraudWatch verification
xTip	String	The tip portion that is included in the total transaction amount (xAmount)
xTax	String	The tax portion that is included in the total transaction amount (xAmount)
xSignature	String	The Base 64 encoded customer signature
xInvoice	String	The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016879",
"xInvoice": "1234567",
"xRefNumCurrent": "10000016886",
"xDate": "7/11/2022 4:06:11 PM"
}

Adjust - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:adjust",
    "xAmount": "35.00",
    "xCustom01": "Register01",
    "xCustom02": "Register01",
    "xCustom03": "Register01",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xRefNum": "81234568",
    "xName": "John Doe",
    "xDescription": "This is a description",
    "OrderID": "123456",
    "xTip": "1.05",
    "xTax": "1.05",
    "xSignature": "aGVsbG8gaG93IGFyZSB5b3UK",
    "xInvoice": "123456A"
}

Save

POST cc:save

xCommand = cc:Save The Save command is used to send account information and to request a token from Cardknox. It does not submit the transaction for processing. The response returns a token that references the account information. A token at minimum references the credit card number, but if other data is sent—such as a billing address—it will be associated with the token as well.

AvsOnly When AvsOnly is enabled for cc:Save, in addition to just generating a token, the transaction will be submitted to the bank for AVS and CVV verification. This setting can be turned on in the Cardknox backend settings.

Request Body

Name	Type	Description
xCardNum*	String	The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.
xExp*	String	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
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0.
xSoftwareName*	String	Name of your software
xCommand*	String	Cardknox transaction type
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xMagstripe	String	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.
xName	String	The cardholder’s name.
xIP	String	The customer’s IP address. Typically used for fraud detection.
xSoftwareVersion*	String	Version number of your software
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.
xCVV	String	3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)

200: OK

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016898",
"xExp": "1030",
"xDate": "7/11/2022 4:15:15 PM",
"xToken": "38gn292893h0nq72m0qn69892q9mg56g",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa"
}

Save - Request Payload Example

{
    "xCardNum": "4444333322221111",
    "xExp": "1249",
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:save",
    "xCustom01": "Register01",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
    "xName": "John Doe",
    "xIP": "1.1.1.1"
}

AvsOnly ($0 Auth)

POST cc:avsonly

xCommand = cc:AvsOnly An AVS Only transaction allows you to verify the accuracy of a customer's billing address without processing the payment. This type of transaction is useful for validating the authenticity of the billing address before completing a purchase. It can also be use to verify the card CVV

To perform an AVS Only transaction, you need to send the customer's billing address details along with the request. The bank will then compare the provided address against the billing address on file with the card issuer and return a response indicating whether the address matches or not.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
xCVV	String	3-digit code from the back of the card (for Amex, 4-digit code from the front of the card).
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xMagstripe	String	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.
xName	String	The cardholder’s name
xIP	String	The customer’s IP address. Typically used for fraud detection.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.
xCommand*	String	Cardknox transaction type
xCardNum*	String	The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.
xExp*	String	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
xCVV	String	3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)

Credit

POST cc:credit

xCommand = cc:Credit

To issue a credit (refund) through our API without referring to a previous sale, you can use the following command: cc:credit

Please note that our system blocks credits on cards that do not have a prior sale by default. To allow such credits to go through, you must send a request to [e-mail].

Request Body

Name	Type	Description
xCardNum*	String	The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.
xExp*	String	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.
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0.
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount*	String	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction.
xToken	String	The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.
xCustom01*	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
xCVV	String	3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)
xStreet	String	The billing street address of the cardholder
xZip	String	The billing zip code of the cardholder
xMagstripe	String	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
xName	String	The cardholder’s name
xDUKPT	String	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	String	The tax portion that is included in the total transaction amount (xAmount)
xTip	String	The tip portion that is included in the total transaction amount (xAmount)
xInvoice	String	The merchant’s invoice number for the transaction. xInvoice is recommended when available for improved duplicate handling.
xPONum	String	The merchant’s purchase order number for the transaction
xComments	String	Additional data optionally passed along to the receipt
xDescription	String	Additional data that is optionally passed along for reporting
xIP	String	The customer’s IP address. Typically used for fraud detection.
xEmail	String	The customer’s email address
xFax	String	The customer’s fax number
xBillFirstName	String	The customer’s first name for their billing profile
xBillMiddleName	String	The customer’s middle name or initial for their billing profile
xBillLastName	String	The customer’s last/family name for their billing profile
xBillCompany	String	The customer’s company name for their billing profile
xBillStreet	String	The customer’s street address for their billing profile
xBillStreet2	String	The customer’s street address 2nd line for their billing profile
xBillCity	String	The customer’s city for their billing profile
xBillState	String	The customer’s state for their billing profile
xBillZip	String	The customer’s zip code for their billing profile
xBillCountry	String	The customer’s country for their billing profile
xBillPhone	String	The customer’s phone number for their billing profile
xBillMobile	String	The customer’s mobile number for their billing profile
xShipFirstName	String	The customer’s first name for their shipping profile
xShipMiddleName	String	The customer’s middle name or initial for their shipping profile
xShipLastName	String	The customer’s last/family name for their shipping profile
xShipCompany	String	The customer’s company name for their shipping profile
xShipStreet	String	The customer’s street address for their shipping profile
xShipStreet2	String	The customer’s street address 2nd line for their shipping profile
xShipCity	String	The customer’s city for their shipping profile
xShipState	String	The customer’s state for their shipping profile
xShipZip	String	The customer’s zip code for their shipping profile
xShipCountry	String	The customer’s country for their shipping profile
xShipPhone	String	The customer’s phone number for their shipping profile
xShipMobile	String	The customer’s mobile number for their shipping profile
xOrderId	String	Unique order number for FraudWatch verification
xExistingCustomer	String	Yes/No value indicating if the customer is a repeat customer
xAllowDuplicate	String	By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xCustReceipt	String	True/False value indicating if the email address specified in xemail should receive a receipt containing the transaction details.
xCurrency	String	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. (see list of all supported currencies).
xTimeoutSeconds	String	Configurable amount of seconds in which the request will wait for a response.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016908",
"xInvoice": "123456",
"xExp": "1030",
"xAuthCode": "78685A",
"xBatch": "14594556",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "M",
"xCvvResult": "Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xToken": "n701mmg5qm3969673q92hm0p652h2n9g",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:21:17 PM",
"xEntryMethod": "Keyed"
}

Credit - Request Payload Example

{
    "xCardNum": "4444333322221111",
    "xExp": "1030",
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:credit",
    "xAmount": "35.00",
    "token": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
    "xCustom01": "Register01",
    "xCVV": "123",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xMagstripe": "%B4444333322221111^TEST CARD/VISA^4912101123456789?;4444333322221111=4912101123456789?",
    "xName": "John Doe",
    "xDUPKT": 
    "xTax": "2.00",
    "xTip": "2.00",
    "xInvoice": "123456A",
    "xPONum": "123456B",
    "xComments": "This is a comment",
    "xDescription": "This is a description",
    "xIP": "1.2.3.4",
    "xEmail": "[e-mail]",
    "xFax": "1234567890",
    "xBillFirstName": "John",
    "xBillMiddleName": "Max",
    "xBillLastName": "Doe",
    "xBillCompany": "Acme", 
    "xBillStreet": "123 Any Street", 
    "xBillStreet2": "Apt 4b", 
    "xBillCity": "Anytown", 
    "xBillState": "NY", 
    "xBillZip": "12345", 
    "xBillCountry": "USA", 
    "xBillPhone": "8005551212", 
    "xBillMobile": "8005551111", 
    "xShipFirstName": "John", 
    "xShipMiddleName": "Max", 
    "xShipLastName": "Doe", 
    "xShipCompany": "Acme", 
    "xShipStreet": "123 Any Street", 
    "xShipStreet2": "Apt 4b", 
    "xShipCity": "Anytown", 
    "xShipState": "NY", 
    "xShipZip": "11111", 
    "xShipCountry": "USA", 
    "xShipPhone": "8005551212", 
    "xShipMobile": "8005551111", 
    "xAllowPartialAuth": "TRUE",
    "xRxAmount": "1.50",
    "xDentalAmount": "1.50",
    "xVisionAmount": "1.50",
    "xTransitAmount": "1.50",
    "xCopayAmount": "1.50",
    "xClinicalAmount": "1.50",
    "xOrderID": "12356",
    "xExistingCustomer": "TRUE",
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "TRUE",
    "xCurrency": "USD",
    "xTimeoutSeconds": "10"
}

Refund

POST cc: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.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0.
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xAmount	String	Refund amount. Can be equal or less than the original transaction.
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
xAllowDuplicate	String	By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed.
xDescription	String	Additional data optionally passed along for reporting
xRefNum*	String	Used to reference a previous transaction when processing 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).
xCustReceipt	String	True/False value indicating if the email address specified in xemail should receive a receipt containing the transaction details
xTimeoutSeconds	String	Configurable amount of seconds in which the request will wait for a response.
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016913",
"xInvoice": "123456",
"xExp": "1030",
"xAuthCode": "41174A",
"xBatch": "14594556",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:27:32 PM",
"xEntryMethod": "Unknown"
}

Refund - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:refund",
    "xAmount": "35.00",
    "xCustom01": "Register01",
    "xRefNum": "93827163", 
    "xDescription": "This is a description",
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "FALSE",
    "xCurrency": "USD",
    "xTimeoutSeconds": "10"
}

VoidRefund

POST cc:voidrefund

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.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0
xSoftwareName*	String	Name of your software
xSoftwareVersion*	String	Version number of your software
xCommand*	String	Cardknox transaction type
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
xRefNum*	String	Used to reference a previous transaction when processing 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).
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

200: OK

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016915",
"xInvoice": "123456",
"xRefNumCurrent": "10000016916",
"xExp": "1030",
"xAvsResultCode": "NNN",
"xAvsResult": "Address: No Match & 5 Digit Zip: No Match",
"xCvvResultCode": "N",
"xCvvResult": "No Match",
"xAuthAmount": "35.00",
"xMaskedCardNumber": "4xxxxxxxxxxx1111",
"xCardType": "Visa",
"xToken": "h9n16qg990p99157640h6m823942934p",
"xMID": "xxxxxxxxxx9999",
"xTID": "xxxxx6789",
"xCurrency": "USD",
"xDate": "7/11/2022 4:30:38 PM",
"xEntryMethod": "Unknown"
}

VoidRefund - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:voidrefund",
    "xCustom01": "Register01",
    "xRefNum": "93827163"
}

VoidRelease

POST cc:voidrelease

xCommand = cc:voidrelease The VoidRelease command releases a pending authorization amount back to the cardholder’s credit limit without waiting for the standard authorization time frame to expire.

Request Body

Name	Type	Description
xKey*	String	Your Cardknox API key.
xVersion*	String	Gateway API version. The current version is 5.0.0
xSoftwareName*	String