USIO ACH
This page provides an overview of the payments methods provided by the USIO ACH adapter in the IXOPAY platform. It also includes a full list of all configuration options available to you when integrating USIO ACH within your payments landscape, as well as an overview of the parameters required when submitting a transaction via IXOPAY's API.
Process US domestic ACH debits, refunds and payouts via the USIO Payments API.
Supported features
Payment methods
The table below lists the payment methods that USIO ACH supports. It also includes the available processing options and the supported transaction types for each of those payment methods.
| Payment method | Processing options | Transaction types |
|---|---|---|
ACH Direct Debit (ACHDirectDebit) | Server-to-server Hosted payment page | Debit Debit with register Register Refund (full amount only) Payout |
The merchant either submits the payer's bank account details with the transaction, or leaves them out and lets the payer enter them on the gateway's hosted payment form, see Hosted payment form. There is no payment.js integration.
The following transaction types are not supported:
| Transaction type | Reason |
|---|---|
| Void | Cancel or reverse a debit with a Refund instead, see Refund and void |
| Preauthorize / Capture | ACH has no authorization step |
| Incremental authorization | ACH has no authorization step |
| Partial refund | Rejected before it is sent to USIO |
| Deregister | USIO offers no API to delete a token |
Currencies
USD only. A Debit, Payout or token debit in any other currency is rejected with INVALID_REQUEST_DATA before it is sent to USIO.
Connector configuration
Connector options, payout credentials and the required reconciliation Data Fetcher are described in the USIO page of the User Manual.
Bank account details
The payer's bank account is passed in extraData on the transaction:
extraData.routingNum: ABA routing number, exactly 9 digitsextraData.accNum: bank account number, 1 to 17 charactersextraData.accType:checkingorsavings
The account type and the direction of the transaction determine the NACHA transaction code sent to USIO:
| Account type | Debit and Register | Payout |
|---|---|---|
checking | 27 | 22 |
savings | 37 | 32 |
All three fields are required for a Payout. For a Debit or Register they can be left out and are then collected on the hosted payment form. A debit with a reusable token does not need them, see Register and token debit.
Hosted payment form
A Debit, Debit with register or Register that arrives without some of the data USIO requires returns a redirectUrl. The payer enters the missing data on the gateway's hosted payment form, and the transaction is then submitted to USIO exactly as if the data had been in the request. No connector configuration is needed.
The form is shown when any of these is missing or empty:
extraData.routingNum,extraData.accNum,extraData.accTypecustomer.firstName,customer.lastName,customer.email,customer.billingAddress1,customer.billingCity,customer.billingState,customer.billingPostcode
A request carrying all of them is processed server-to-server, without a redirect.
The form always shows all of these fields. Values the request already carried are shown read-only and cannot be changed by the payer; the account number is shown masked to its last four digits. The payer fills in only the empty fields.
A value that is present but malformed (for example an 8-digit routing number), a currency other than USD and a missing or invalid SEC code are rejected with INVALID_REQUEST_DATA straight away, without a redirect: the payer could not correct them on the form.
After the payer submits the form, the SEC code, NACHA WEB account validation and the submission to USIO run exactly as for a server-to-server request. If the validation or the submission fails, the transaction fails and the payer is sent to the errorUrl. The payer cannot retry on the same transaction.
The form is never shown for a Payout, a Refund or a token debit.
Before the hosted payment form was available, a Debit or Register missing bank account or customer data failed immediately with INVALID_REQUEST_DATA. It now returns a redirectUrl instead. Integrations that relied on that error to detect missing data have to send the data, or handle the redirect.
NACHA SEC code
Every Debit, Register and Payout needs a NACHA Standard Entry Class (SEC) code: WEB, PPD, TEL or CCD.
Send it per transaction as extraData.standardEntryCode, or set the standardEntryCode connector option as the default.
The transaction value takes precedence. If neither provides a valid value, the transaction is rejected with INVALID_REQUEST_DATA.
NACHA WEB account validation
NACHA requires that a bank account is validated before it is debited via a WEB entry for the first time (NACHA WEB Debit Account Validation Rule, effective 2021-03-19).
When the SEC code is WEB, every Debit, Register and Payout that carries bank account details is first checked with USIO's VerifyACHAccount. A debit with a reusable token is not validated again.
VerifyACHAccount result | Outcome |
|---|---|
| Success, account unknown to USIO | The transaction is submitted as usual |
Success, message Account Closed | The transaction is not submitted. It fails with ACCOUNT_CLOSED_EXTERNALLY, message NACHA WEB account validation failed: account closed, not resubmittable |
Failure (Status is not success) | The transaction is not submitted. The error is mapped like any other USIO failure, see Error codes |
| No response (timeout, connection error) | The transaction is not submitted and fails as resubmittable: nothing was sent to USIO for the payment yet |
The confirmation of the validation is returned as extraData.verifyAchConfirmation, see Response mapping.
VerifyACHAccount always uses the standard credentials, also for a payout that is submitted with the payout credentials.
Register and token debit
A Register stores the bank account at USIO without moving money (USIO TokenizeOnly=true, amount 0.00). It is final immediately: success or error. The USIO Confirmation is stored as the USIO token. The response returns the Register's own UUID as registrationId.
A Debit flagged with register (withRegister) charges the account and also stores the USIO Confirmation as the USIO token. If the debit fails, no token is stored.
A token debit is a Debit that references a successful Register (or a Debit with register) via referenceUuid. It is submitted with USIO's SubmitTokenPayment:
extraData.routingNum,extraData.accNum,extraData.accTypeand the customer data are not required and not sentamountandcurrency(USD) are required- the SEC code is required, from
extraData.standardEntryCodeor the connector option - the optional extraData fields are passed through, except
address2 - NACHA WEB validation is skipped
Stop using a token after certain returns. If a debit is returned with R02 (account closed) or R10 (customer advises unauthorized), stop debiting the token that was used for it, and the token from the Register or Debit with register for that account. The gateway does not block later token debits after a return, so this has to be handled on the merchant side. Collect new bank account details, or for R10 a new authorization from the customer, before debiting again.
extraData.tokenizeOnly is not needed: it is derived from the transaction type. If it is sent and contradicts the transaction type (true on a Debit or Payout, false on a Register), the transaction is rejected with INVALID_REQUEST_DATA.
Refund and void
USIO uses one operation (SubmitACHVoidReturn) to reverse an ACH payment and decides itself, based on the settlement state, whether it is a void (not yet settled) or a return (already settled).
To cancel or reverse a USIO ACH debit, always submit a Refund that references the debit. A Void that references a debit is rejected.
- A refund must be for the full amount of the original debit. Partial refunds are rejected with
INVALID_REQUEST_DATA. - A refund that references a Register is rejected with
NOT_ALLOWED, because no money was moved. - A refund accepted by USIO is final: the refund is
successimmediately. Reconciliation does not report it.
Payout credentials
USIO can provision a separate merchant account for ACH credits. In that case configure the creditMerchantId, creditUsername and creditPassword connector options.
- If all three are set, payouts are submitted with the credit credentials.
- If any of the three is empty, payouts fall back to the standard Username, Password and merchantId.
Each payout returns the credential set it used as extraData.credentialContext (credit or standard).
Running USIO ACH and USIO PCI side by side: the two connectors handle payout credentials differently. USIO PCI Pinless Debit payouts do not fall back to the standard credentials, and use differently named fields (CreditMerchantID, CreditLogin, CreditPassword). Configure each connector according to its own rules.
Asynchronous status
USIO does not send webhooks, callbacks or status notifications for API integrations. USIO's postbacks only exist for the USIO hosted payment page, which this adapter does not use. Do not configure or wait for a notification URL at USIO.
USIO ACH resolves the final status of a Debit or Payout only through reconciliation. Without a reconciliation Data Fetcher configured for the connector, every Debit and Payout stays pending forever. Set it up as described in the USIO Data Fetcher configuration in the User Manual.
With the daily interval USIO recommends, expect the final status on the business day after USIO has batched the payment.
A successful response to a Debit or Payout only means that USIO accepted the payment: the transaction is pending.
The final status is resolved by the reconciliation data fetcher, which reads USIO's achbatch and achreturn reports (GetTransactionList), and is sent to the merchant as a status notification to the callback URL.
| USIO report row | Gateway status | Meaning |
|---|---|---|
achbatch row with a BatchNumber | success | USIO has sent the payment to the ACH network in a batch |
achreturn row with a ReturnDate | error | The payment was returned, the NACHA return code is kept on the error |
Row without BatchNumber and without ReturnDate | pending | USIO has not batched the payment yet |
success means batched, not settled. It confirms that USIO submitted the payment to the ACH network. It does not confirm that the funds have reached or left the payer's account: ACH settlement typically takes one to three business days after batching, and the payment can still be returned.
Returns after success
NACHA returns (R-codes) arrive asynchronously and can arrive after a transaction was reported as success. For example, a consumer can return a debit as unauthorized (R10) up to 60 calendar days after settlement.
Whether a return changes a success transaction to error automatically depends on the Allow Success to Error reconciliation setting of the connector. Otherwise the return is raised as a reconciliation conflict and has to be resolved manually.
Mapping to USIO ACH
This segment provides a comprehensive guide to effectively integrate USIO ACH into your payment procedure. It offers a detailed mapping between the fields of the gateway and corresponding fields on the USIO side. Furthermore, it outlines the requisite fields which must be delivered per specific transaction type.
Optional fields are only sent to USIO when they are set. Empty values are omitted.
Parameters
Request mapping
| Gateway parameter | USIO parameter | Type | Description | Transaction types |
|---|---|---|---|---|
extraData.routingNum | RoutingNumber | required stringExactly 9 digits | ABA routing number | only: Debit, Register, Payout |
extraData.accNum | AccountNumber | required string1 to 17 characters | Bank account number | only: Debit, Register, Payout |
extraData.accType | TransCode | required stringone of: [ checking, savings ] | Account type, mapped to the NACHA transaction code, see Bank account details | only: Debit, Register, Payout |
extraData.standardEntryCode | StandardEntryCode | required stringone of: [ WEB, PPD, TEL, CCD ]Falls back to the standardEntryCode connector option | NACHA SEC code | |
amount | Amount | required string | Transaction amount. A Register always sends 0.00 | only: Debit, Payout |
currency | — | required stringone of: [ USD ] | Only validated, not sent | only: Debit, Payout |
merchantTransactionId | MerchantPayAccount | required string | Merchant's transaction reference | |
referenceUuid | Token | required stringOnly for a token debit | References a successful Register or Debit with register. Its USIO Confirmation is sent as the token | only: Debit |
customer.firstName | FirstName | required string | only: Debit, Register, Payout | |
customer.lastName | LastName | required string | only: Debit, Register, Payout | |
customer.email | EmailAddress | required string | only: Debit, Register, Payout | |
customer.billingAddress1 | Address1 | required string | only: Debit, Register, Payout | |
customer.billingCity | City | required string | only: Debit, Register, Payout | |
customer.billingState | State | required string | only: Debit, Register, Payout | |
customer.billingPostcode | Zip | required string | only: Debit, Register, Payout | |
extraData.address2 | Address2 | optional string? | Second billing address line. Not sent on a token debit | only: Debit, Register, Payout |
extraData.additionalSearch | AdditionalSearch | optional string? | Free search field in the USIO portal. Recommended to carry the gateway transaction UUID | |
extraData.accountCode1 | AccountCode1 | optional string? | Merchant-defined reference | |
extraData.accountCode2 | AccountCode2 | optional string? | Merchant-defined reference | |
extraData.accountCode3 | AccountCode3 | optional string? | Merchant-defined reference | |
extraData.achOpt1 | ACHOpt1 | optional string? | USIO ACH option field | |
extraData.sameDayAch | SameDayACH | optional string? | Request same-day ACH processing | |
extraData.addendaData | AddendaData | optional string? | NACHA addenda record data | |
extraData.description | Description | optional string? | Payment description | |
extraData.officeId | OfficeID | optional string? | USIO office identifier | |
extraData.convFeeAmount | ConvFeeAmount | optional string? | Convenience fee amount | |
extraData.tokenizeOnly | TokenizeOnly | optional boolean? | Derived from the transaction type. Rejected if it contradicts it | only: Debit, Register, Payout |
| (connector option) checkNegativeAccounts | CheckNegativeAccounts | booleanDefaults to true when empty | Check the account against USIO's negative accounts list. A value that is not a boolean fails with INVALID_CONFIGURATION | only: Debit, Register, Payout |
| (connector option) disableDuplicateCheck | DisableDuplicateCheck | booleanDefaults to false when empty | Disable USIO's duplicate check. A value that is not a boolean fails with INVALID_CONFIGURATION | only: Debit, Register, Payout |
A refund sends only the original payment's USIO Confirmation (ConfirmationID) and the full original amount.
Response mapping
The USIO Confirmation of a submitted payment is stored as the adapter transaction ID. It is used to match reconciliation rows, as the reference for a refund and, for a Register or a Debit with register, as the USIO token for later token debits. It is not returned in the API response on success.
The API response returns the following fields in extraData:
| Gateway parameter | USIO parameter | Type | Description | Transaction types |
|---|---|---|---|---|
extraData.confirmation | Confirmation | optional string? | USIO confirmation, returned on a refund and on a failed submission when USIO sent one | |
extraData.verifyAchConfirmation | Confirmation of VerifyACHAccount | optional string? | Confirmation of the NACHA WEB account validation, also returned when the validation fails | only: Debit, Register, Payout |
extraData.credentialContext | — | stringone of: [ standard, credit ] | Credential set the payout was submitted with, see Payout credentials | only: Payout |
A successful Register returns registrationId, which is the UUID of the Register transaction, not the USIO token. Reference the Register by this UUID (referenceUuid) for a token debit.
Callback mapping
USIO sends no callbacks. Status updates come from reconciliation, see Asynchronous status.
Error codes
The USIO response code or NACHA return code is available as the adapter code of the transaction error.
| USIO error code | Gateway error code | Message | Resubmit |
|---|---|---|---|
1100 | TRANSACTION_DECLINED | Account is on the negative accounts list | No |
5112 | DUPLICATE_TRANSACTION_ID | Duplicate transaction | No |
5116 | NOT_ALLOWED | Void/refund is not allowed against a tokenize-only registration | No |
5078, 5079, 5096, 5097, 5098 | INVALID_REQUEST_DATA | Invalid ACH data | No |
Account Closed (VerifyACHAccount) | ACCOUNT_CLOSED_EXTERNALLY | NACHA WEB account validation failed: account closed | No |
R01, R02, R10, … (any R-code) | TRANSACTION_DECLINED | ACH payment returned (Rxx) | No |
| (any other USIO failure) | PROCESSING_ERROR | USIO's own message | — |
NACHA return codes are passed through unchanged, so every R-code reaches the transaction error, not only the examples above. Common ones are R01 (insufficient funds), R02 (account closed) and R10 (customer advises unauthorized).
Requests that fail validation before they are sent to USIO (currency, customer fields, bank account details, SEC code, partial refund) fail with INVALID_REQUEST_DATA. On a Debit or Register, missing bank account details or customer fields send the payer to the hosted payment form instead. An invalid checkNegativeAccounts or disableDuplicateCheck connector value fails with INVALID_CONFIGURATION.
Ambiguous responses
If the gateway does not receive a clear answer from USIO for a Debit, Register, Payout or Refund (timeout, connection error, server error, or a success without a Confirmation), the transaction fails with mayResubmit set to false: USIO may already have accepted it. Do not resubmit it.
If USIO did accept it, reconciliation reports it. With the Allow Error to Success reconciliation setting the transaction is updated automatically, otherwise the difference is raised as a reconciliation conflict.
Examples
Debit
Request:
{
"merchantTransactionId": "2026-10-05-0001",
"amount": "9.99",
"currency": "USD",
"callbackUrl": "https://api.example.org/callback",
"customer": {
"firstName": "Alex",
"lastName": "Smith",
"billingAddress1": "123 Main Street",
"billingCity": "Springfield",
"billingState": "IL",
"billingPostcode": "62701",
"billingCountry": "US"
},
"extraData": {
"routingNum": "555555550",
"accNum": "123456789",
"accType": "checking",
"standardEntryCode": "WEB",
"additionalSearch": "2026-10-05-0001"
}
}
Response:
{
"success": true,
"uuid": "abcde12345abcde12345",
"purchaseId": "20261005-abcde12345abcde12345",
"returnType": "PENDING",
"paymentMethod": "ACHDirectDebit",
"extraData": {
"verifyAchConfirmation": "261005021217HYR"
}
}
The debit stays PENDING until reconciliation reports the final status. verifyAchConfirmation is only returned when the SEC code is WEB.
Register
Same request as the debit, without amount and currency. The response is final:
{
"success": true,
"uuid": "fghij67890fghij67890",
"purchaseId": "20261005-fghij67890fghij67890",
"registrationId": "fghij67890fghij67890",
"returnType": "FINISHED",
"paymentMethod": "ACHDirectDebit",
"extraData": {
"verifyAchConfirmation": "26100506125262A"
}
}
Token debit
Reference the successful Register with referenceUuid. No bank account or customer data is needed:
Request:
{
"merchantTransactionId": "2026-11-05-0001",
"amount": "9.99",
"currency": "USD",
"referenceUuid": "fghij67890fghij67890",
"callbackUrl": "https://api.example.org/callback",
"extraData": {
"standardEntryCode": "PPD"
}
}
Response:
{
"success": true,
"uuid": "klmno24680klmno24680",
"purchaseId": "20261105-klmno24680klmno24680",
"returnType": "PENDING",
"paymentMethod": "ACHDirectDebit"
}
A token debit is not validated again, so no verifyAchConfirmation is returned.
Payout
Request:
{
"merchantTransactionId": "2026-10-05-0002",
"amount": "25.00",
"currency": "USD",
"callbackUrl": "https://api.example.org/callback",
"customer": {
"firstName": "Alex",
"lastName": "Smith",
"billingAddress1": "123 Main Street",
"billingCity": "Springfield",
"billingState": "IL",
"billingPostcode": "62701",
"billingCountry": "US"
},
"extraData": {
"routingNum": "555555550",
"accNum": "123456789",
"accType": "checking",
"standardEntryCode": "WEB"
}
}
Response:
{
"success": true,
"uuid": "pqrst13579pqrst13579",
"purchaseId": "20261005-pqrst13579pqrst13579",
"returnType": "PENDING",
"paymentMethod": "ACHDirectDebit",
"extraData": {
"verifyAchConfirmation": "261005062303QBT",
"credentialContext": "standard"
}
}
Refund
Reference the debit with referenceUuid and send the full original amount:
Request:
{
"merchantTransactionId": "2026-10-06-0001",
"referenceUuid": "abcde12345abcde12345",
"amount": "9.99",
"currency": "USD",
"callbackUrl": "https://api.example.org/callback"
}
Response:
{
"success": true,
"uuid": "uvwxy97531uvwxy97531",
"purchaseId": "20261005-abcde12345abcde12345",
"returnType": "FINISHED",
"paymentMethod": "ACHDirectDebit",
"extraData": {
"confirmation": "261006023920EW5"
}
}
The refund is final immediately and carries the purchaseId of the debit it refunds.
Testing
With Testmode enabled, the connector uses the USIO sandbox (https://devpayments.usiopay.com) instead of production (https://payments.usiopay.com). Sandbox credentials are provided by USIO.
The following bank account is accepted in the sandbox for Debit, Register and Payout:
| Routing number | Account number | Account type | Result |
|---|---|---|---|
555555550 | 123456789 | checking | Passes NACHA WEB validation and is accepted by USIO. Debit and Payout are pending, Register is success |
-
A sandbox payment is batched like a production payment, and reconciliation sets it to
success. In the sandbox, theBatchNumberof a batched row is the literal valueTest. -
No callbacks are sent in the sandbox either: run the reconciliation data fetcher to move a transaction out of
pending. -
Validation rules (USD only, 9-digit routing number, SEC code, full-amount refund,
tokenizeOnlyconflicts) are applied before USIO is called, so they can be tested with any sandbox account. -
NACHA returns are triggered by the amount, for Debit and Payout alike. Once reconciliation reads the return row, the transaction is set to
errorwith the messageACH payment returned (Rxx)and the R-code as the adapter code:Amount Return code Result 1.01USDR01error,ACH payment returned (R01)— insufficient funds1.02USDR02error,ACH payment returned (R02)— account closed -
There is no known sandbox data that triggers a NACHA WEB
Account Closedresult or response code1100(negative accounts list). These cases cannot currently be reproduced in the sandbox. Contact USIO if you need to test them.