Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.uphold.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the steps to support ACH bank deposits using the REST API — from generating deposit instructions to monitoring for the incoming transfer.

​
Prerequisites

​
Walkthrough

​
Check available rails

Call List Rails to verify ACH supports the deposit feature before proceeding. 
GET /core/rails?type=bank&network=ach&asset=USD
A successful response includes the rail details. The constraints field indicates that US rail deposits can only be credited to the user’s default USD account, regardless of the network used. 
{
  "rails": [
    {
      "type": "bank",
      "network": "ach",
      "method": "bank-transfer",
      "asset": "USD",
      "decimals": 2,
      "features": [
        "deposit",
        "withdraw"
      ],
      "constraints": [
        {
          "rule": "allowed-deposit-accounts",
          "allowed": "default-only"
        }
      ]
    }
  ]
}

​
Select destination account

USD bank deposits can only be credited to the user’s default USD account.

​
Find the default account

Call List default accounts to retrieve it. 
GET /core/accounts/defaults?asset=USD

{
  "accounts": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "ownerId": "1e32fca3-23f7-40ed-bc1b-de10c790182d",
      "label": "My USD account",
      "asset": "USD",
      "balance": {
        "total": "100.00",
        "available": "100.00"
      }
    }
  ]
}

​
Create a new account

If the user has no default USD account, create one with Create account before proceeding. 
POST /core/accounts
{
  "label": "My USD account",
  "asset": "USD"
}

{
  "account": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "ownerId": "1e32fca3-23f7-40ed-bc1b-de10c790182d",
    "label": "My USD account",
    "asset": "USD",
    "balance": {
      "total": "0",
      "available": "0"
    }
  }
}

​
Generate deposit method

For US bank rails, the same account and routing number are shared across all networks (ACH, FedNow / RTP, and Wire), so the same deposit method is generated and can be used for any of these networks. Call Set up account deposit method with the target account id and the desired network. For subsequent calls, use Get account deposit method instead. 
PUT /core/accounts/{accountId}/deposit-method?type=bank&network=ach&asset=USD
Use network=fednow or network=wire to generate instructions branded for those networks instead. A successful response includes the bank details for the user to initiate the transfer. 
{
  "depositMethod": {
    "type": "bank",
    "status": "ok",
    "details": {
      "network": "ach",
      "asset": "USD",
      "routingNumber": "021000021",
      "accountNumber": "123456789",
      "accountType": "checking",
      "beneficiary": "John Doe",
      "bankName": "Cross River Bank",
      "bankAddress": {
        "line1": "2 Riverview Dr",
        "line2": "Fort Lee, NJ 07024"
      },
      "secondaryNetworks": [
        "fednow",
        "wire"
      ]
    }
  }
}
The deposit method may initially return status: processing while the details are being prepared. Call Get account deposit method to make sure the deposit method is ready (status: ok) before displaying instructions to the user.
Provide the routing number, account number and account type. Include the beneficiary name, bank name, and bank address to help the user confirm the legitimacy of the instructions. No reference is provided because all deposits are credited to the default USD account.

​
Monitor for the incoming transfer

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

​
Sample transaction

In a successful ACH bank deposit, the origin is represented as a bank-address node. The destination is the user’s default USD account. 
{
  "transaction": {
    "id": "a2b3c4d5-e6f7-8a9b-c0d1-e2f3a4b5c6d7",
    "origin": {
      "asset": "USD",
      "amount": "500.00",
      "node": {
        "type": "bank-address",
        "network": "ach"
      }
    },
    "destination": {
      "asset": "USD",
      "amount": "500.00",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "status": "completed",
    "quotedAt": "2025-06-15T14:00:00Z",
    "createdAt": "2025-06-15T14:10:00Z",
    "updatedAt": "2025-06-15T14:30:00Z",
    "denomination": {
      "asset": "USD",
      "amount": "500.00",
      "target": "origin"
    }
  }
}

​
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 deposits via the REST API.