ACH Payments & Returns

How ACH works on USAePay

ACH is a US bank-to-bank debit. Unlike a card authorisation, which is confirmed in
real time, an ACH debit is only accepted for processing when it is submitted —
the customer's bank can return it days later for insufficient funds, a closed
account, or a dispute.

USAePay accepts the payment immediately and reports the return separately, so
Shuttle holds the transaction as Pending until it knows the outcome.

What the customer enters

• Routing number
• Account number
• Account type — Checking or Savings

Limitations

ACH on USAePay is sale-only:

• USD only. A non-USD ACH payment is rejected.
• No saved bank accounts. USAePay cannot tokenise a bank account, so an ACH
  payment method cannot be stored.
• No recurring ACH. With no stored payment method, ACH cannot be used for
  contracts or scheduled charges. Use cards for recurring payments on this gateway.
• No authorise / capture / void. ACH is a straight sale; refunds are supported.

The transaction lifecycle

• Payment submitted — USAePay accepts the debit. The transaction is recorded as
  Pending, not Approved.
• Settled — the funds clear. The transaction is marked Approved.
• Returned — the customer's bank rejects the debit. The transaction is marked
  Failed, with the return reason recorded against it (for example
  R01:Insufficient Funds).

A hard decline at submission time — bad routing number, blocked account — fails
immediately, the same as a card decline.

How Shuttle finds out

Scheduled polling (always on). Shuttle re-queries the payment on a schedule
until it reaches a final state. ACH cannot settle in less than a day, so the first
check is 48 hours after the payment, then daily for up to 9 further checks —
roughly 11 days of cover. A payment that is still unresolved at the end of that is
marked Unresolved for manual review rather than being guessed at.

Webhooks (optional, faster). If you configure a USAePay webhook, Shuttle is
notified as soon as the payment settles or is returned, instead of waiting for the
next scheduled check. The webhook only acts as a trigger — Shuttle always re-reads
the authoritative status from USAePay before changing anything, because USAePay can
deliver events out of order.

Polling is the floor: if a webhook is missed, misconfigured, or fails its signature
check, the scheduled poll still reconciles the payment.

Setting up the webhook (optional)

Webhooks are configured per merchant account in the USAePay console — there is
no API to register them, so this is a manual step for each merchant.

1. In the USAePay console, open the webhook settings and add an endpoint pointing at
   https://<your Shuttle domain>/webhooks/g/<gateway key>/webhook.
2. Set Auth to off and Signature to Signature Key. USAePay generates a key
   beginning wsig:.
3. Subscribe the endpoint to the ACH events — at minimum ach.settled,
   ach.returned, ach.voided and ach.failed.
4. Copy the Signature Key into the Webhook Signature Key box in the Shuttle
   USAePay gateway settings, including the wsig: prefix, and save.

Shuttle verifies the signature on every inbound webhook and ignores anything that
fails, so an incorrect key degrades to polling rather than corrupting a payment.

USAePay retries a failed delivery progressively over 72 hours and requires TLS 1.2.

Enabling ACH

• Enable ACH on your USAePay account.
• In the Shuttle admin portal, open the USAePay gateway settings and enable
  Enable ACH / Bank Transfer.
• Optionally add the Webhook Signature Key (see above).
• Save the gateway settings.

See Connecting USAePay for the rest of the connection
settings.