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.
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
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
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.
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
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")
For a full list of response codes, see the table in the Introduction page.
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
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.
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.
For a full list of response codes, see the table in the Introduction page.
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
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.
For a full list of response codes, see the table in the Introduction page.
SplitCapture
POST
cc:splitcapture
xCommand
= cc:splitcapture
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 split capture documentation for more information.
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.
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
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.
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
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.
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
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)
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
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 gatewaysupport@cardknox.com.
Request Body
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
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.
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
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.
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
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.
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
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.
Void
POST
cc:void
xCommand
= cc:Void
The Void command voids a transaction that has not yet settled using xRefNum
.
Request Body
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.
Last updated
Was this helpful?