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
Sign in to the Cardknox Merchant Portal.
Select "Account Settings" from the navigation bar.
Select "Keys" from the sub-menu.
Click "Create a Key" in the top-right corner.
Choose the desired key type (API or iFields), description (software, etc.), and permissions.
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
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:
Transactions
Sale
POSTcc: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
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":"text@example.com","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","x1Description":"Wireless Bluetooth Speaker","x1Sku":"12345","x1Qty":"5","x1UnitPrice":"49.99","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
POSTcc: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
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":"text@example.com","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
POSTcc: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
For a full list of response codes, see the table in the Introduction page.
{"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":"text@example.com","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
POSTcc: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.
{"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
POSTcc: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.
{"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)
POSTcc: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
Credit
POSTcc: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 gatewaysupport@cardknox.com.
{"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":"text@example.com","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
POSTcc: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
{"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
POSTcc: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
{"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"}
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
{"xResult": "A","xStatus": "Approved","xError": "","xErrorCode": "00000","xRefNum": "10000016917","xInvoice": "123456","xRefNumCurrent": "10000016919","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","xMID": "xxxxxxxxxx9999","xTID": "xxxxx6789","xCurrency": "USD","xDate": "7/11/2022 4:33:02 PM","xEntryMethod": "Unknown"}