API v4.14
Markdown

ACH / eCheck API

Process electronic funds transfers directly from customer bank accounts, including the ACH transaction lifecycle, supported actions, request parameters, and status values.

ACH & eCheck Transactions

Process electronic funds transfers directly from customer bank accounts. ACH authorization requests will typically return a PENDING status while the funds clear through the banking network.

The following steps describe the lifecycle of a transaction processed with an ACH account:

  1. Customer initiates purchase on the payment page.
  2. Merchant submits transaction request to the Payments Service. This should include the following data: - Customer and payment information. - Merchant gateway credentials and other gateway parameters as needed.
  3. Payments Service transmits the transaction request to the bank.
  4. Merchant receives gateway response. The transaction status should be PENDING.
  5. Post-processing transaction status update (both methods are optional): - Postback API: Payments Service sends a Postback to the merchant as the transaction state changes. Postbacks are real-time. - Order Detail Report: Merchant downloads order and transaction data using the Order Detail Report service.
Note on status updates

If you choose not to use the Postback API or Order Detail Report to receive updates on the status of an ACH order, you can log into our portal and check the status manually by searching for the order ID.

To keep merchants updated on the status of their pending ACH transactions, we can send realtime Postbacks to the merchant.

Merchants may also download transaction status updates as an alternative to Postback by using Order Detail Report service.

Parameter Description
REQUEST_ACTION Required Set to ACHAUTHCAP for Auth/Capture, or ACHAUTHORIZE for validation without capture.
PMT_NUMB Required Customer Bank Account Number.
BANK_IDENTIFIER Required Bank Routing Number.
LI_VALUE_1 Required Transaction Amount.

ACH Actions

Below are the only supported gateway actions for ACH. Any other gateway action or feature will not work.

REQUEST_ACTION Description
ACHAUTHCAP Used for authorization and capture requests.
ACHAUTHORIZE Used for Authorizations without Capture.
ACHREVERSE Used for Authorization Capture Reversal.
ACHCREDIT Used for transaction credit requests.
ACHPAYOUT Used for ACH direct deposit payout.

Handling ACH Responses

Because ACH transactions rely on the banking network to clear funds, initial responses will typically return a PENDING status rather than an immediate approval or decline.

Field Name Description
TRANS_STATUS_NAME Check this to ensure the transaction is PENDING (or APPROVED if the bank clears it instantly).
TRANS_VALUE The amount requested for the transaction.
TRANS_ID The unique Transaction ID for the gateway event.
PO_ID The Purchase Order ID linking to the transaction.
PROC_AUTH_RESPONSE The authorization string generated by the processor.

Auth & capture example

Not in the SDKs yet

ACH is not implemented in any of the four SDKs. BankAccount exists as a declared-but-unconstructible payment method variant (PaymentMethods only builds card, token, savedCard in v1; a BankAccount reaches the wire only by hand-assembling parameters outside the client), and none of sale()/authorize()/reverse()/forceCredit() recognize ACHAUTHCAP, ACHAUTHORIZE, ACHREVERSE, ACHCREDIT or ACHPAYOUT as actions, those five constants appear only as decorative labels in the generated enum files, not as request builders. Use the cURL example directly, or see the SDKs for the v1 card surface.

Authorize only example

Not in the SDKs yet

No SDK builds an ACHAUTHORIZE request. See the SDKs.

Reversal example

Not in the SDKs yet

reverse() exists in all four SDKs, but it only builds CCREVERSE (card reversal), there is no ACHREVERSE path. See the SDKs.

Credit example

Not in the SDKs yet

forceCredit() exists in all four SDKs, but it only builds CCCREDIT (card credit), there is no ACHCREDIT path. See the SDKs.

Payout example

Not in the SDKs yet

ACHPAYOUT has no SDK equivalent in any of the four languages. See the SDKs.

curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=ACHAUTHCAP&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&pmt_numb=1234567890&bank_identifier=987654321&li_value_1=50.00"

curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=ACHAUTHORIZE&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&pmt_numb=1234567890&bank_identifier=987654321&li_value_1=50.00"

curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=ACHREVERSE&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&request_ref_po_id=99281736"

curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=ACHCREDIT&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&request_ref_po_id=99281736&li_value_1=15.00"

curl -X POST "https://api.inoviopay.com/payment/pmt_service.cfm" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "request_action=ACHPAYOUT&req_username=api_user&req_password=P%40ssw0rd%21&site_id=12345&request_api_version=4.14&request_response_format=JSON&pmt_numb=1234567890&bank_identifier=987654321&li_value_1=250.00"

ACH Request Parameters

The table below describes parameters needed in sending ACH purchase request to the gateway. Merchants may send additional parameters, as described in the Payments Payment Service API, such as customer billing address, email, website login and other pass-through data.

Field Name Description
SITE_ID Merchant's Website ID.
LI_PROD_ID_1 Line Item Product ID 1.
LI_VALUE_1 Line Item Transaction Amount 1.
PMT_NUMB Bank Account Number.
BANK_IDENTIFIER Routing Number.
MERCH_ACCT_ID Merchant Account ID.
REQUEST_CURRENCY 3-letter Currency Code.
CUST_FNAME Customer First Name.
CUST_LNAME Customer Last Name.
BILL_ADDR Billing Street Address.
BILL_ADDR_CITY Billing City Name.
BILL_ADDR_STATE Billing State 2-letter Code.
BILL_ADDR_COUNTRY Billing Country 2-letter Code.
BILL_ADDR_ZIP Billing ZIP or Postal Code.

ACH Transaction Status

TRANS_STATUS_NAME Description
APPROVED Transaction has been approved.
PENDING Transaction is in pending status.
RUNNING Transaction processing was not completed or is waiting completion usually because of gateway error.