# ACH / eCheck API

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

Source: https://developer.inoviopay.com/api/ach.html  
Markdown: https://developer.inoviopay.com/api/ach.md

## 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](https://developer.inoviopay.com/sdks/index.md) for the v1 card surface.

### Authorize only example


> **Not in the SDKs yet**
> No SDK builds an `ACHAUTHORIZE` request. See [the SDKs](https://developer.inoviopay.com/sdks/index.md).

### 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](https://developer.inoviopay.com/sdks/index.md).

### 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](https://developer.inoviopay.com/sdks/index.md).

### Payout example


> **Not in the SDKs yet**
> `ACHPAYOUT` has no SDK equivalent in any of the four languages. See [the SDKs](https://developer.inoviopay.com/sdks/index.md).

**cURL**

```bash
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"
```

**Response**

```json
{
  "REQUEST_ACTION": "ACHAUTHCAP",
  "REQ_ID": "67392811",
  "TRANS_STATUS_NAME": "PENDING",
  "TRANS_VALUE": 50.00,
  "CURR_CODE_ALPHA": "USD",
  "TRANS_VALUE_SETTLED": 50.00,
  "CURR_CODE_ALPHA_SETTLED": "USD",
  "TRANS_EXCH_RATE": "",
  "TRANS_ID": 3948572115,
  "CUST_ID": 9827163,
  "XTL_CUST_ID": "",
  "PO_ID": 99281736,
  "XTL_ORDER_ID": "",
  "BATCH_ID": 883925,
  "PROC_NAME": "Inovio ACH Primary",
  "MERCH_ACCT_ID": 141630,
  "CARD_BRAND_NAME": "ACH",
  "CARD_TYPE": "",
  "CARD_PREPAID": 0,
  "CARD_BANK": "",
  "CARD_DETAIL": "",
  "CARD_BALANCE": "",
  "PMT_L4": "7890",
  "PMT_ID": 8839210,
  "PMT_ID_XTL": "",
  "PMT_AAU_UPDATE_DT": "",
  "PMT_AAU_UPDATE_DESC": "",
  "PROC_UDF01": "",
  "PROC_UDF02": "",
  "PROC_AUTH_RESPONSE": "PEND992",
  "PROC_RETRIEVAL_NUM": "A1B2C3D4-E5F6-7A8B-9C0D-E1F2A3B4C5D6",
  "PROC_REFERENCE_NUM": "REF88291039",
  "PROC_REDIRECT_URL": "",
  "AVS_RESPONSE": "M",
  "CVV_RESPONSE": "M",
  "CARD_BRAND_TRANSID": "",
  "REQUEST_API_VERSION": "4.14",
  "P3DS_VENDOR": "",
  "P3DS_RESPONSE": "",
  "PO_LI_ID_1": "9928178",
  "PO_LI_COUNT_1": 1,
  "PO_LI_AMOUNT_1": "50.00",
  "PO_LI_PROD_ID_1": "136381",
  "MBSHP_ID_1": "",
  "TRANS_NTOKEN_USED": 0
}
```

**cURL**

```bash
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"
```

**Response**

```json
{
  "REQUEST_ACTION": "ACHAUTHORIZE",
  "REQ_ID": "67392812",
  "TRANS_STATUS_NAME": "PENDING",
  "TRANS_VALUE": 50.00,
  "CURR_CODE_ALPHA": "USD",
  "TRANS_VALUE_SETTLED": 50.00,
  "CURR_CODE_ALPHA_SETTLED": "USD",
  "TRANS_EXCH_RATE": "",
  "TRANS_ID": 3948572116,
  "CUST_ID": 9827163,
  "PO_ID": 99281737,
  "BATCH_ID": 883925,
  "PROC_NAME": "Inovio ACH Primary",
  "MERCH_ACCT_ID": 141630,
  "CARD_BRAND_NAME": "ACH",
  "PMT_L4": "7890",
  "PMT_ID": 8839210,
  "PROC_AUTH_RESPONSE": "PEND993",
  "PROC_RETRIEVAL_NUM": "B2C3D4E5-F6A7-8B9C-0D1E-2F3A4B5C6D7E",
  "REQUEST_API_VERSION": "4.14",
  "PO_LI_ID_1": "9928179",
  "PO_LI_AMOUNT_1": "50.00"
}
```

**cURL**

```bash
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"
```

**Response**

```json
{
  "REQUEST_ACTION": "ACHREVERSE",
  "TRANS_STATUS_NAME": "APPROVED",
  "TRANS_VALUE": -10,
  "CURR_CODE_ALPHA": "USD",
  "TRANS_VALUE_SETTLED": -10,
  "CURR_CODE_ALPHA_SETTLED": "USD",
  "TRANS_EXCH_RATE": "",
  "TRANS_ID": 3948572120,
  "CUST_ID": 9827164,
  "XTL_CUST_ID": "",
  "PO_ID": 99281739,
  "XTL_ORDER_ID": "",
  "BATCH_ID": 883926,
  "PROC_NAME": "ACHProcessor",
  "MERCH_ACCT_ID": 141630,
  "CARD_BRAND_NAME": "",
  "CARD_DETAIL": "",
  "CARD_TYPE": "",
  "CARD_PREPAID": "",
  "CARD_BANK": "",
  "PMT_L4": "4567",
  "PMT_ID": 8839211,
  "PMT_ID_XTL": "",
  "PROC_UDF01": "",
  "PROC_UDF02": "",
  "PROC_AUTH_RESPONSE": "",
  "PROC_RETRIEVAL_NUM": "",
  "PROC_REFERENCE_NUM": "",
  "PROC_REDIRECT_URL": "",
  "AVS_RESPONSE": "",
  "CVV_RESPONSE": "",
  "REQ_ID": "84729106",
  "REQUEST_API_VERSION": "4.14",
  "PO_LI_ID_1": "9928183",
  "PO_LI_COUNT_1": 1,
  "PO_LI_AMOUNT_1": -10,
  "PO_LI_PROD_ID_1": "12345",
  "MBSHP_ID_1": ""
}
```

**cURL**

```bash
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"
```

**Response**

```json
{
  "REQUEST_ACTION": "ACHCREDIT",
  "TRANS_STATUS_NAME": "",
  "TRANS_VALUE": "",
  "TRANS_ID": "",
  "REQ_ID": "84729105",
  "CUST_ID": "9928104",
  "XTL_CUST_ID": "xT883mP",
  "PMT_ID": "",
  "MERCH_ACCT_ID": "141630",
  "CARD_BRAND_NAME": "",
  "PMT_L4": "",
  "API_RESPONSE": "0",
  "API_ADVICE": " ",
  "SERVICE_RESPONSE": 512,
  "SERVICE_ADVICE": "Order not found",
  "PROCESSOR_RESPONSE": 0,
  "PROCESSOR_ADVICE": " ",
  "INDUSTRY_RESPONSE": 0,
  "INDUSTRY_ADVICE": " ",
  "REF_FIELD": "",
  "PROC_NAME": "",
  "AVS_RESPONSE": "",
  "CVV_RESPONSE": "",
  "PROC_REDIRECT_URL": "",
  "REQUEST_API_VERSION": "4.14",
  "TRANS_NTOKEN_USED": 0
}
```

**cURL**

```bash
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"
```

**Response**

```json
{
  "REQUEST_ACTION": "ACHPAYOUT",
  "TRANS_STATUS_NAME": "",
  "TRANS_VALUE": "",
  "TRANS_ID": "",
  "REQ_ID": "84729104",
  "CUST_ID": 9928103,
  "XTL_CUST_ID": "xT883mP",
  "PMT_ID": 8829103,
  "MERCH_ACCT_ID": "110203",
  "CARD_BRAND_NAME": "ACH",
  "PMT_L4": "7890",
  "API_RESPONSE": "0",
  "API_ADVICE": " ",
  "SERVICE_RESPONSE": 522,
  "SERVICE_ADVICE": "Unsupported card brand",
  "PROCESSOR_RESPONSE": 0,
  "ANI_RESP_DECISION": "",
  "PROCESSOR_ADVICE": " ",
  "INDUSTRY_RESPONSE": 0,
  "INDUSTRY_ADVICE": " ",
  "REF_FIELD": "",
  "PROC_NAME": "",
  "AVS_RESPONSE": "",
  "CVV_RESPONSE": "",
  "PROC_REDIRECT_URL": "",
  "REQUEST_API_VERSION": "4.14",
  "TRANS_NTOKEN_USED": 0
}
```

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