Skip to main content
This guide walks you through the steps to support ACH bank withdrawals using the REST API — from creating an external account to monitoring for settlement.

Prerequisites

Walkthrough


Check available rails

Before creating a quote, verify the ACH rail is available for withdrawals. Call List Rails for USD to confirm the ach network has the withdraw feature.

Select source account

ACH withdrawals can be sourced from any account. If the selected account is not in USD, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them pick the one to withdraw from.

Select a bank account

ACH bank accounts are not linked automatically. Users must provide their routing and account number to add one. Select an existing linked account or add a new one.

Find an existing bank account

Call List external accounts and filter for accounts with type: "bank". If no USD bank account exists, proceed to link one.
Make sure the selected account has status: "ok" and "withdraw" in features.
Create a USD bank account by calling Create external account with the user’s bank details.
The details.secondaryNetworks.withdraw field is present only when the destination bank supports FedNow. If it appears, you may use "fednow" as the network in the quote to settle funds faster.

Create a quote

Create a quote with Create quote. Pass network: "ach" on the destination node to route the transfer via ACH, or leave it out to route via the external account’s default network. If the external account has secondaryNetworks, the user can choose which one to use for the transfer. The quote must be created with the selected network to ensure accurate fees and expiration time.
A successful response returns a quote object with fees and expiration.
Quotes are short-lived. Use refreshAt to drive re-quoting: if the user hasn’t confirmed by then, create a new quote and show the updated amounts, since there’s no refresh endpoint. The quote’s expiresAt is equal to or later than refreshAt, to give the user time to complete an external action needed to proceed, such as authorizing an APM payment.

Confirm and create transaction

After the user confirms the withdrawal, call Create transaction with the quote ID to execute the transfer.
In a successful ACH withdrawal, the origin is the user’s account and the destination is the external-account representing the user’s bank. The transaction status is initially processing and updates to completed once the transfer settles.

Monitor for settlement

Prefer webhooks for real-time updates, or fall back to polling if webhooks are not feasible.

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.
You now support ACH bank transfer withdrawals via the REST API.

Request errors

Create quote and Create transaction reject a request with an HTTP error when it can’t go ahead, in which case no transaction is created. The table only lists the errors your integration should act on, such as by showing the user a message. The other errors usually point to an issue in your integration. See the API reference of each endpoint for the full list.

Failure reasons

A transaction that was created can still fail afterwards: its status becomes failed, or on-hold when information is requested, and statusDetails.reason says why. You learn about it through the core.transaction.status-changed webhook, or by polling Get transaction. The table only lists the reasons your integration should act on, such as by notifying the user.