Check (ACH)
Overview
This page contains all API documentation for Check (ACH), and ACH-Q transactions. For more information regarding account access, navigate to the Transaction API parent page.
How to Generate Cardknox Keys
Sign in to the Cardknox Merchant Portal.
Select "Account Settings" from the navigation bar.
Select "Keys" from the sub-menu.
Click "Create a Key" in the top-right corner.
Choose the desired key type (API or iFields), description (software, etc.), and permissions.
Click "Create and View" and copy your key.
It is critical to copy your key and save it in a secure location, as you won’t be able to obtain the key again.
Endpoints
Health Check
HTTP Request Method: GET
Transactions
HTTP Request Method: POST
Cardknox allows you to send the data in FormData, JSON, and XML formats.
Add to the base URL any of the following formats to indicate which format you are sending it as:
FormData | /gatewayform | https://x1.cardknox.com/gatewayform |
JSON | /gatewayjson | https://x1.cardknox.com/gatewayjson |
XML | /gatewayxml | https://x1.cardknox.com/gatewayxml |
Transactions
Cardknox provides ACH and ACHQ processing for the transactions listed below (with exception of VoidRefund, which there is only ACHQ processing for). For more information regarding ACHQ, refer to the ACHQ Developer Page or contact Cardknox support.
Sale
POST
check:sale
xCommand
= check:Sale
The Check Sale command debits funds from a customer’s checking or savings account using one of the following options:
The merchant must have a supported Check/ACH processing account to use either of these options.
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. |
xToken | String | The Cardknox token that references a previously used payment method. When using a token, |
xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use |
xRouting* | String | The check ABA routing number |
xAccount* | String | The check account number |
xName* | String | Name on account |
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. |
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 |
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 |
xMICR | String | The routing, account and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner |
xCheckNum | String | The check number |
xCheckImageFront | String | The front image of the check, in Base 64 encoded image format. |
xCheckImageRear | String | The back image of the check, in Base 64 encoded image format. |
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 |
xCurrency | String | Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (see list of all supported currencies). |
xBillMobile | String | The customer’s mobile number for their billing profile |
xAccountType | String | Type of account: Checking or Savings |
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. |
Save
POST
check:save
xCommand
= check:Save
The Save command is used to send account information and request a token from Cardknox but does not submit the transaction for processing. The response returns a token that references the account information. A token at minimum references the account and routing number, but if other data is sent—such as billing address—that will be associated with the token as well.
Request Body
Name | Type | Description |
---|---|---|
xCommand* | String | Cardknox transaction type |
xRouting* | String | The check ABA routing number |
xName* | String | The cardholder’s name |
xSoftwareName* | String | Name of your software |
xSoftwareVersion* | String | Version number of your software |
xAccount* | String | The check account number |
xVersion* | String | Gateway API version. The current version is 5.0.0 |
xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use |
xKey* | String | Your Cardknox API key. |
xIP | String | The customer’s IP address. Typically used for fraud detection. |
xMICR | String | The routing, account, and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner |
xAllowDuplicate | String | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
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
check:void
xCommand
= check:Void
The Void command voids a check transaction that is pending being sent to the bank, typically at the end of each day.
Request Body
Name | Type | Description |
---|---|---|
xKey* | String | Your Cardknox API key. |
xVersion* | String | Gateway API version. The current version is 5.0.0 |
xSoftwareName* | String | Name of your software |
xSoftwareVersion* | String | Version number of your software |
xCommand* | String | Cardknox transaction type |
xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use |
xRefNum* | String | Used to reference a previous transaction when processing a follow-up transaction; typically a refund, void, or capture. (Note: |
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. |
Refund
POST
check:refund
xCommand
= check:Refund
The Refund command is used to refund the full amount of a previously settled check transaction, using xRefNum
. Partial check refund isn’t 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 |
xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use |
xRefNum* | String | Used to reference a previous transaction when processing a follow-up transaction; typically a refund, void, or capture. (Note: |
xIP | String | The customer’s IP address. Typically used for fraud detection. |
xAmount* | String | The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the transaction. |
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 |
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
check:VoidRefund
xCommand
= check:VoidRefund
The VoidRefund within the ACHQ tooling is used void a check transaction that is pending being sent to the bank, typically at the end of each day. It also issues a refund. Partial refunds are also supported.
Request Body
Name | Type | Description |
---|---|---|
xCommand* | String | Cardknox transaction type |
xRouting* | String | The check ABA routing number |
xName | String | The cardholder’s name. One of xName, xBillFirstName, or xBillLastName are required. |
xSoftwareName* | String | Name of your software |
xSoftwareVersion* | String | Version number of your software |
xAccount* | String | The check account number |
xVersion* | String | Gateway API version. The current version is 5.0.0 |
xCustom01 | String | 20 custom fields are available for custom data, such as customer comments, etc. Use |
xKey* | String | Your Cardknox API key. |
xIP | String | The customer’s IP address. Typically used for fraud detection. |
xMICR | String | The routing, account, and check number data from the bottom of a check in MICR (Magnetic Ink Character Recognition) format, typically generated by a check scanner |
xAllowDuplicate | String | By default, Cardknox rejects duplicate transactions within 10 minutes of the original transaction. This command overrides that safeguard. True/False allowed. |
xSupports64BitRefnum | String | True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction. |
xBillState* | String | Company Billing State |
xBillCity* | String | Company Billing City |
xBillStreet* | String | Company Street Address |
xBillCompany* | String | Required if xCheckType = Business |
xBillZip* | String | Company Billing Zip |
xBillPhone* | String | Company Phone Number |
xEmail* | String | Company Email |
xCheckType* | String | Check Type (Business, Personal) |
Check (ACH) FAQ
Q: How many days does it take to get the ACH status?
A: It typically takes 2-3 days.
Q: How can I get the ACH status?
A: There are a few ways to get the status. Via email, webhook, the Cardknox Portal, or by pulling a report using our reporting API.
Q: What verbiage comes back from the ACH Status?
A: You should get back the following status codes from Cardknox:
xStatus=16 “settled”
xStatus=14 “chargeback”
xStatus=0 “pending”
The daily emails may contain more information.
Q: Can we get back a token when using the check MICR?
A: Cardknox only returns tokens on check transactions that contain the routing and account number. In the event only check images and MICR were submitted, the token is not returned since it can’t be reused on subsequent transactions.
Last updated