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.

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.

Note: The use of check/ACH transactions requires compliance with Nacha regulations, including the requirement to capture a physical or electronic signature from the customer. Please ensure your integration meets these compliance standards.

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.
xRouting*	String	The check ABA routing number
xAccount*	String	The check account number
xName*	String	Name on account
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.
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
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 xemail should receive a receipt containing the transaction details
xCurrency	String	Used to specify an alternate currency. Only applicable for accounts that are using Multi-Currency Conversion (MCC). For accounts that are natively in a foreign currency, the currency does not need to be specified. (see list of all supported currencies).
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.
xPaymentOrigin	String	Origin of payment. Possible values: "Internet" (denoting web transactions) "SignatureOriginal" (denoting transactions with physical signature)

Sale - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "check:sale",
    "xAmount": "35.00",
    "xToken": "61h72mmh68phn9q233634ph3g54p1499m69qhp4816pn528h84",
    "xCustom01": "Register01",
    "xRouting": "123456789",
    "xAccount": "123456789",
    "xAccountType": "Checking",
    "xName": "John Doe",
    "xTax": "2.00",
    "xTip": "2.00",
    "xInvoice": "123456A",
    "xPONum": "123456B",
    "xComments": "This is a comment",
    "xDescription": "This is a description",
    "xIP": "1.2.3.4",
    "xEmail": "[e-mail]",
    "xFax": "1234567890",
    "xBillFirstName": "John",
    "xBillMiddleName": "Max",
    "xBillLastName": "Doe",
    "xBillCompany": "Acme", 
    "xBillStreet": "123 Any Street", 
    "xBillStreet2": "Apt 4b", 
    "xBillCity": "Anytown", 
    "xBillState": "NY", 
    "xBillZip": "12345", 
    "xBillCountry": "USA", 
    "xBillPhone": "8005551212", 
    "xBillMobile": "8005551111", 
    "xShipFirstName": "John", 
    "xShipMiddleName": "Max", 
    "xShipLastName": "Doe", 
    "xShipCompany": "Acme", 
    "xShipStreet": "123 Any Street", 
    "xShipStreet2": "Apt 4b", 
    "xShipCity": "Anytown", 
    "xShipState": "NY", 
    "xShipZip": "11111", 
    "xShipCountry": "USA", 
    "xShipPhone": "8005551212", 
    "xShipMobile": "8005551111", 
    "xMICR": "t021000021t 123456789o _2542",
    "xCheckNum": "999",
    "xCheckImageFront": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/w",
    "xCheckImageRear": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAYEBAQFBAYFBQYJBgUGCQsIBgYICwwKCgsKCgwQDAwMDAwMEAwODxAPDgwTExQUExMcGxsbHCAgICAgICAgICD/2wBDAQcHBw0MDRgQEBgaFREVGiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICD/w",
    "xOrderID": "12356",
    "xExistingCustomer": "TRUE",
    "xAllowDuplicate": "TRUE", 
    "xCustReceipt": "TRUE",
    "xCurrency": "USD",
    "xTimeoutSeconds": "10",
    "xPaymentOrigin": "Internet"
}

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
xKey*	String	Your Cardknox API key.
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
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.

Save - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "check.save",
    "xCustom01": "Register01",
    "xRouting": "123456789",
    "xAccount": "123456789",
    "xName": "John Doe",
    "xIP": "1.2.3.4",
    "xMICR": "t021000021t 123456789o _2542",
    "xAllowDuplicate": "TRUE"
}

Adjust

POST check: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. Any non-required field can be adjusted.

Request Body

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
xAmount*	String	The total amount of the transaction, inclusive of tax and tip if applicable. This the total amount of the 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). *The xRefNum from the related authorization is required when submitting an Adjust transaction.
xCustom01 – xCustom03	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
xSupports64BitRefnum	String	True/False value indicating that the user’s system can handle a 64bit refnum getting returned on request to the transaction.

Adjust - Request Payload

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

200 - Response

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

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

Void - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "check.void",
    "xCustom01": "Register01",
    "xRefNum": "81726356",
    "xIP": "1.1.1.1"
}

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
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	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.
xIP	String	The customer’s IP address. Typically used for fraud detection.
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.
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 - Request Payload Example

{
    "xKey": "[xkeycredentials]",
    "xVersion": "4.5.9",
    "xSoftwareName": "YourSoftwareName",
    "xSoftwareVersion": "1.0.0",
    "xCommand": "check.refund",
    "xAmount": "9.99",
    "xCustom01": "Register01",
    "xRefNum": "81726356",
    "xIP": "1.1.1.1",
    "xAllowDuplicate": "TRUE",
    "xCustReceipt": "FALSE",
    "xTimeoutSeconds": "10"
}

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
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
xKey*	String	Your Cardknox API key.
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)
xName	String	The cardholder’s name. One of xName, xBillFirstName, or xBillLastName are required.
xCustom01	String	20 custom fields are available for custom data, such as customer comments, etc. Use xCustom01 through xCustom20.
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.

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.