Cardknox is now Sola
Learn More
LogoLogo
Contact Us
  • Introduction
  • 🔗API
    • Transaction API
      • Credit Card
      • Check (ACH)
      • EBT
      • Gift Card
      • Fraud
    • Customer and Recurring API
    • Reporting API
    • Account Boarding API
      • Account Boarding Merchant Agreement
      • Account Boarding Swagger UI
    • Code Samples
    • Error Codes
  • 📦SDK
    • .NET SDK
      • Transaction Workflow
    • iOS SDK
      • iOS SDK - Technical Guide
      • Workflow
    • Android SDK
      • Android SDK - Technical Guide
  • 🧰 Cardknox Products
    • 3D Secure 2.0
      • Client-Side Integration
        • Client-Side Integration (Non-iFields)
      • Server-Side Integration
    • Account Updater
    • Batch Processing
    • Browser-Based POS systems (BBPOS)
    • CloudIM Developer Guide
    • Deep Linking
      • Deep Linking Integration for Third-Party Websites
    • EBT Online
    • Gateway Emulators
    • iFields
      • Angular iFields
    • Merchant Portal
      • FAQ
    • Mobile App
    • Split Capture
    • Tap to Phone - Android
    • Partner Portal
    • PaymentSITE
      • QR Codes for PaymentSITE
    • Webhooks
  • 📱Mobile Wallets
    • Apple Pay Hosted Checkout
      • Apple Pay Hosted Checkout Initial Setup
      • Apple Pay Prerequisites
      • Apple Pay Hosted Checkout Objects Reference (Request)
      • Apple Pay Hosted Checkout Objects Reference (Response)
      • Apple Pay iFields Integration
      • Apple Pay Hosted Checkout Sample Code
      • Apple Pay Features
      • Set up Apple Pay Merchant ID with Cardknox
    • Click-To-Pay - Hosted Checkout
      • Click-To-Pay Initial Setup
      • Click-To-Pay Sample Code
      • Click-To-Pay iFields Integration
      • Click-To-Pay Objects Reference (Request)
      • Click-To-Pay Objects Reference (Response)
    • Google Pay Hosted Checkout
      • Google Pay Control Object
      • Google Pay Request Objects
      • Google Pay Response Objects
      • Google Pay Sample Code
      • iFields Integration
      • Google Pay FAQ
  • 🔌Plugins
    • Netsuite
      • NetSuite Features and Demo
    • WooCommerce
    • Magento Plugin
    • RMH (Retail Management Hero)
    • RMS (Retail Management Systems)
  • 📖Articles
    • Frequently Asked Questions
    • How to Build POS Integration Flows
    • Card Present Integration Guide
  • Glossary of Terms
Powered by GitBook
On this page
  • Overview
  • Transactions
  • Sale
  • AuthOnly
  • Capture
  • SplitCapture
  • Adjust
  • Save
  • AvsOnly ($0 Auth)
  • Credit
  • Refund
  • VoidRefund
  • VoidRelease
  • Void

Was this helpful?

Export as PDF
  1. API
  2. Transaction API

Credit Card

Last updated 2 months ago

Was this helpful?

Overview

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

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 command initially and then use the 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.

xCardNum*

String

The customer card number. *Alternatively, xToken xMagStripe or SUT can be used.

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

x1Description

String

Line Item product description. Increment the “1“ for additional items.

x1Sku

String

Line Item product sku. Increment the “1“ for additional items.

x1Qty

String

Line Item product quantity. Increment the “1“ for additional items.

x1UnitPrice

String

Line Item product price. Increment the “1“ for additional items.

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.

xAllowNonAuthenticated

String

True/False value, enabling a customer to complete a purchase without needing to verify their identity through a separate authentication step. Defaults to 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

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

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")

{
"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",
    "xHotelChargeType": "Direct",
    "xHotelRoomRate": "159.99",
    "xHotelNoShow": "TRUE",
    "xAllowPartialAuth": "TRUE",
    "xAllowNonAuthenticated": "FALSE",
    "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

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)

xRequireSplitCapturable

String

Indicate if you want to ensure that the authorization will allow split capture. When this is set to true and split capture is not supported, an error will be returned “Split capture not supported“.

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.

xHotelChargeType

String

The charge type for the transaction.

xHotelRoomRate

String

The nightly room rate for the hotel.

xHotelNoShow

String

True/False indicating whether customer was a no-show.

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

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.

{
"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",
    "xRequireSplitCapturable": "TRUE",
    "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",
    "xIncremental": "TRUE",
    "xSupports64BitRefnum": "TRUE"
}

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

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).

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.

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.

{
"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": "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"
}

SplitCapture

POST cc:splitcapture

xCommand = cc:splitcapture

xKey*

String

Your Cardknox API key

xVersion*

String

Gateway API Version. The current version is 5.0.0.

xCommand*

String

Cardknox transaction type

xSoftwareName*

String

Name of your software

xSoftwareVersion*

String

Version number of your software

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).

xAmount*

String

The portion of the authorized funds to capture in the current SplitCapture request.

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.

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 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

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.

Capture - Response Payload
{
    "xKey": "[xkeycredentials]",
    "xVersion": "5.0.0",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:splitcapture",
    "xRefNum": "81234568",
    "xAmount": "9.99",
    "xCustom01": "Register01",
    "xStreet": "123 Main Street",
    "xZip": "12345",
    "xName": "John Doe",
    "xTax": ".05",
    "xTip": ".05",
    "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",
    "xSupports64BitRefnum": "TRUE"
}
SplitCapture - Response Payload
{
"xResult":"A",
"xStatus":"Approved",
"xError":"",
"xErrorCode":"00000",
"xRefNum":"10230508134",
"xInvoice":"123456",
"xExp":"1030",
"xAuthCode":"74119A",
"xBatch":"5128394",
"xAvsResultCode":"NNN",
"xAvsResult":"Address:No Match & 5 Digit Zip: No Match",
"xCvvResultCode":"",
"xCvvResult":"No CVV data available",
"xAuthAmount":"10.00",
"xMaskedCardNumber":"4xxxxxxxxxxx1111",
"xCardType":"Visa",
"xToken":"h0n6m0gn70m99598hp282802h60q2911",
"xMID":"xxxxxxxxxx9999",
"xTID":"xxxxx6789",
"xCurrency":"USD",
"xDate":"1/29/2025 10:58:54 AM",
"xEntryMethod":"Unknown"
}

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. If xIncremental field is not set to True in cc:AuthOnly, use of xAmount in will result in forced cc:Adjust transaction.

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).

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

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

xIncremental

String

Incremental authorizations enable increase the authorized amount on a captured transaction. True/False value. Must be set to True in order for xAmount to be used in cc:Adjust, otherwise cc:Adjust will be a forced transaction.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

{
"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",
    "xIncremental": "TRUE"
}

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

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.

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.

xCVV

String

3-digit code from the back of the card (for Amex, 4-digit code from the front of the card)

{
"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

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

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.

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

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.

xCustom01*

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xToken

String

The Cardknox token that references a previously used payment method. When using a token, xCardNum xExp and xMagstripe should not be used.

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

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.

{
"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": "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

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

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).

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

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.

{
"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

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).

xCustom01

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

{
"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

Name of your software

xSoftwareVersion*

String

Version number of your software

xCommand*

String

Cardknox transaction type

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).

xCustom01

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

{
"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"
}

VoidRelease - Request Payload Example
{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:voidrelease",
    "xCustom01": "Register01",
    "xRefNum": "93827163"
}

Void

POST cc:void

xCommand = cc:Void The Void command voids a transaction that has not yet settled using xRefNum.

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

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).

xCustom01

String

20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.

xSupports64BitRefnum

String

True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

{
"xResult": "A",
"xStatus": "Approved",
"xError": "",
"xErrorCode": "00000",
"xRefNum": "10000016875",
"xInvoice": "123456",
"xRefNumCurrent": "10000016882",
"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:03:04 PM",
"xEntryMethod": "Unknown"
}
Void - Request Payload Example
{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "cc:void",
    "xCustom01": "Register01",
    "xRefNum": "93827163"
}

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 ().

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

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

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 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, 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.

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. ().

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

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

The SplitCapture command is used to capture funds in multiple stages from a single authorization. This is useful for scenarios where the total transaction amount is not settled all at once, such as partial shipments or staged payments. Each SplitCapture request requires the xRefNum of the authorization and allows capturing different amounts up until the authorized amount. See for more information.

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 .

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. ().

🔗
Transaction API
authonly
capture
table
capture
Void Release
table
table
split capture documentation
gatewaysupport@cardknox.com
see list of all supported currencies
here
see list of all supported currencies
see list of all supported currencies