Skip to main content

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 methodProcessing optionsTransaction 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 typeReason
VoidCancel or reverse a debit with a Refund instead, see Refund and void
Preauthorize / CaptureACH has no authorization step
Incremental authorizationACH has no authorization step
Partial refundRejected before it is sent to USIO
DeregisterUSIO 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 digits
  • extraData.accNum: bank account number, 1 to 17 characters
  • extraData.accType: checking or savings

The account type and the direction of the transaction determine the NACHA transaction code sent to USIO:

Account typeDebit and RegisterPayout
checking2722
savings3732

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.accType
  • customer.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.

Behaviour change

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 resultOutcome
Success, account unknown to USIOThe transaction is submitted as usual
Success, message Account ClosedThe 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.accType and the customer data are not required and not sent
  • amount and currency (USD) are required
  • the SEC code is required, from extraData.standardEntryCode or 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 success immediately. 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.

A reconciliation Data Fetcher is required

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 rowGateway statusMeaning
achbatch row with a BatchNumbersuccessUSIO has sent the payment to the ACH network in a batch
achreturn row with a ReturnDateerrorThe payment was returned, the NACHA return code is kept on the error
Row without BatchNumber and without ReturnDatependingUSIO 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 parameterUSIO parameterTypeDescriptionTransaction types
extraData.routingNumRoutingNumberrequired string
Exactly 9 digits
ABA routing numberonly: Debit, Register, Payout
extraData.accNumAccountNumberrequired string
1 to 17 characters
Bank account numberonly: Debit, Register, Payout
extraData.accTypeTransCoderequired string
one of: [ checking, savings ]
Account type, mapped to the NACHA transaction code, see Bank account detailsonly: Debit, Register, Payout
extraData.standardEntryCodeStandardEntryCoderequired string
one of: [ WEB, PPD, TEL, CCD ]
Falls back to the standardEntryCode connector option
NACHA SEC code
amountAmountrequired stringTransaction amount. A Register always sends 0.00only: Debit, Payout
currency—required string
one of: [ USD ]
Only validated, not sentonly: Debit, Payout
merchantTransactionIdMerchantPayAccountrequired stringMerchant's transaction reference
referenceUuidTokenrequired string
Only for a token debit
References a successful Register or Debit with register. Its USIO Confirmation is sent as the tokenonly: Debit
customer.firstNameFirstNamerequired stringonly: Debit, Register, Payout
customer.lastNameLastNamerequired stringonly: Debit, Register, Payout
customer.emailEmailAddressrequired stringonly: Debit, Register, Payout
customer.billingAddress1Address1required stringonly: Debit, Register, Payout
customer.billingCityCityrequired stringonly: Debit, Register, Payout
customer.billingStateStaterequired stringonly: Debit, Register, Payout
customer.billingPostcodeZiprequired stringonly: Debit, Register, Payout
extraData.address2Address2optional string?Second billing address line. Not sent on a token debitonly: Debit, Register, Payout
extraData.additionalSearchAdditionalSearchoptional string?Free search field in the USIO portal. Recommended to carry the gateway transaction UUID
extraData.accountCode1AccountCode1optional string?Merchant-defined reference
extraData.accountCode2AccountCode2optional string?Merchant-defined reference
extraData.accountCode3AccountCode3optional string?Merchant-defined reference
extraData.achOpt1ACHOpt1optional string?USIO ACH option field
extraData.sameDayAchSameDayACHoptional string?Request same-day ACH processing
extraData.addendaDataAddendaDataoptional string?NACHA addenda record data
extraData.descriptionDescriptionoptional string?Payment description
extraData.officeIdOfficeIDoptional string?USIO office identifier
extraData.convFeeAmountConvFeeAmountoptional string?Convenience fee amount
extraData.tokenizeOnlyTokenizeOnlyoptional boolean?Derived from the transaction type. Rejected if it contradicts itonly: Debit, Register, Payout
(connector option) checkNegativeAccountsCheckNegativeAccountsboolean
Defaults to true when empty
Check the account against USIO's negative accounts list. A value that is not a boolean fails with INVALID_CONFIGURATIONonly: Debit, Register, Payout
(connector option) disableDuplicateCheckDisableDuplicateCheckboolean
Defaults to false when empty
Disable USIO's duplicate check. A value that is not a boolean fails with INVALID_CONFIGURATIONonly: 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 parameterUSIO parameterTypeDescriptionTransaction types
extraData.confirmationConfirmationoptional string?USIO confirmation, returned on a refund and on a failed submission when USIO sent one
extraData.verifyAchConfirmationConfirmation of VerifyACHAccountoptional string?Confirmation of the NACHA WEB account validation, also returned when the validation failsonly: Debit, Register, Payout
extraData.credentialContext—string
one of: [ standard, credit ]
Credential set the payout was submitted with, see Payout credentialsonly: 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 codeGateway error codeMessageResubmit
1100TRANSACTION_DECLINEDAccount is on the negative accounts listNo
5112DUPLICATE_TRANSACTION_IDDuplicate transactionNo
5116NOT_ALLOWEDVoid/refund is not allowed against a tokenize-only registrationNo
5078, 5079, 5096, 5097, 5098INVALID_REQUEST_DATAInvalid ACH dataNo
Account Closed (VerifyACHAccount)ACCOUNT_CLOSED_EXTERNALLYNACHA WEB account validation failed: account closedNo
R01, R02, R10, … (any R-code)TRANSACTION_DECLINEDACH payment returned (Rxx)No
(any other USIO failure)PROCESSING_ERRORUSIO'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",
"email": "[email protected]",
"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",
"email": "[email protected]",
"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 numberAccount numberAccount typeResult
555555550123456789checkingPasses 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, the BatchNumber of a batched row is the literal value Test.

  • 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, tokenizeOnly conflicts) 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 error with the message ACH payment returned (Rxx) and the R-code as the adapter code:

    AmountReturn codeResult
    1.01 USDR01error, ACH payment returned (R01) — insufficient funds
    1.02 USDR02error, ACH payment returned (R02) — account closed
  • There is no known sandbox data that triggers a NACHA WEB Account Closed result or response code 1100 (negative accounts list). These cases cannot currently be reproduced in the sandbox. Contact USIO if you need to test them.