> ## Documentation Index
> Fetch the complete documentation index at: https://dev.enterprise.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# USD virtual accounts

> A US account and routing number in your customer's name, at Lead Bank or Erebor Bank. Receives ACH, wire, SWIFT, and FedNow deposits and converts them to stablecoins. Covers eligibility, SSN and ITIN, FedNow, third-party deposits, pay by reference, and ACH microdeposits.

A USD virtual account gives your customer a US account number and routing number in their own name. ACH, wire, and international SWIFT deposits convert to the Autoramp's stablecoin, and FedNow deposits do too where it's enabled.

## Who can get one

| Customer | Eligible |
| - | - |
| Individual living outside the EEA and UK | Yes |
| Individual living in the EEA or UK | No |
| Business | Yes |

MoonPay Enterprise opens the account at **Lead Bank** or **Erebor Bank**, depending on your account's configuration and which bank the customer is eligible for. `bank_name` in `deposit_rails` shows which one holds it.

## Requirements

* The customer is `Active` and `fiat_deposit.usd.ach` reads `Active` in `GET /api/customers/{customer_id}/abilities`. See [Before you create a virtual account](https://dev.enterprise.moonpay.com/onramp.md#before-you-create-a-virtual-account).
* Customers who live in the US provide an SSN or ITIN during KYC. See [KYC](https://dev.enterprise.moonpay.com/kyc.md).
* US sole proprietorships provide a tax ID and a phone number for the proprietor during KYB. See [KYB](https://dev.enterprise.moonpay.com/kyb.md).

If KYC is approved but USD still reads `Pending`, the bank is still opening the customer's account. Subscribe to the `customer_fiat_abilities` webhook to hear when it turns `Active`.

## Create a USD virtual account

In the dashboard, click **New Virtual Account** on the **Onramp** card under **Routes** and pick USD. Through the API:

```bash theme={null}
curl -X POST "https://api.sandbox.iron.xyz/api/autoramps" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "X-API-Key: <your-api-key>" \
  -H "X-API-Version: 2026-07-01" \
  -d '{
    "source_currencies": [{ "type": "Fiat", "code": "USD" }],
    "destination_currency": { "type": "Crypto", "token": "USDC", "blockchain": "Solana" },
    "recipient_account": {
      "type": "Crypto",
      "chain": "Solana",
      "address": "3DkNYk8xJ9xGd1WsKZz8kG3n3QNB4f4pJ3m5mYxBV4Lm"
    },
    "customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

> [!NOTE]
>
> `POST /api/autoramps` requires an `Idempotency-Key` header. A missing key returns `400`. Only successful responses are cached, so a retry after an error runs again. See [Idempotency](https://dev.enterprise.moonpay.com/idempotency.md).

A Lead Bank account opens in the first provisioning run after you create the Autoramp, and the Autoramp moves straight to `Approved`. An Erebor Bank account is ready once Erebor assigns the account number. Either way, share the details only once the Autoramp is `Approved`.

## What your customer sees

An `Approved` USD Autoramp returns one entry per rail in `deposit_rails`. All of them carry the same account number.

```json theme={null}
"deposit_rails": [
  {
    "type": "ACH",
    "routing_number": "123456789",
    "account_number": "9876543210",
    "bank_name": "Lead Bank",
    "bank_address": "1801 Main St.\nKansas City, MO 64108",
    "recipient_name": "Jane Doe",
    "recipient_address": ""
  },
  {
    "type": "Wire",
    "routing_number": "123456789",
    "account_number": "9876543210",
    "bank_name": "Lead Bank",
    "bank_address": "1801 Main St.\nKansas City, MO 64108",
    "recipient_name": "Jane Doe",
    "recipient_address": ""
  },
  {
    "type": "FedNow",
    "routing_number": "123456789",
    "account_number": "9876543210",
    "bank_name": "Lead Bank",
    "bank_address": "1801 Main St.\nKansas City, MO 64108",
    "recipient_name": "Jane Doe",
    "recipient_address": ""
  },
  {
    "type": "SWIFT",
    "bic": "LEADUS49",
    "account_number": "9876543210",
    "bank_name": "Lead Bank",
    "bank_address": "1801 Main St.\nKansas City, MO 64108",
    "recipient_name": "Jane Doe",
    "recipient_address": ""
  }
]
```

| Field | Description |
| - | - |
| `routing_number` | ABA routing number. On `ACH`, `Wire`, and `FedNow` |
| `bic` | BIC for international deposits. On `SWIFT` only: `LEADUS49` for Lead Bank, `ERNAUS33` for Erebor Bank |
| `account_number` | The customer's account number, the same on every rail |
| `bank_name` | `Lead Bank` or `Erebor Bank, N.A.` |
| `bank_address` | The bank's address |
| `recipient_name` | The account holder: your customer's verified name |
| `recipient_address` | Returned as an empty string |
| `memo` | `SWIFT` only, and only when present |

### Which rails appear

* **ACH, Wire, and SWIFT:** on every USD account.
* **FedNow:** on Lead Bank accounts only, when FedNow deposits are enabled for your account and you send `X-API-Version: 2026-07-01` or later. FedNow deposits are accepted only from customers in the US and Canada. A FedNow deposit for any other customer is returned.
* **RTP:** not available. `rtp` never reads `Active` in production, though sandbox reports it as `Active`.

## Third-party deposits

Every USD rail accepts payments from third parties, on first-party and third-party Autoramps alike. A customer who can't hold a Lead Bank account gets a third-party Autoramp whatever the flag says.

On USD transactions, `third_party_classification` is evaluated only on Lead Bank accounts for Autoramps created with `source_is_third_party`. Erebor Bank deposits never carry it. See [Third-party deposits](https://dev.enterprise.moonpay.com/onramp.md#third-party-deposits).

## Pay by reference

USD Autoramps support [pay by reference](https://dev.enterprise.moonpay.com/autoramp.md#pay-by-reference). Each Autoramp on the shared account gets an `inbound_payment_reference` such as `IR-K7M2QX`. MoonPay Enterprise matches it case-insensitively, and finds it inside longer text such as `Invoice 1234 IR-K7M2QX`, but only in one field per rail:

* **ACH at Lead Bank:** the entry's statement descriptor
* **Wire at Lead Bank:** the message to the beneficiary (`message_to_creditor`)

A reference anywhere else doesn't match, and the deposit is returned.

> [!WARNING]
>
> FedNow and pay by reference don't mix. FedNow deposits arrive without a reference, so on an account that has any pay-by-reference Autoramp they're returned. Don't share FedNow details for a pay-by-reference account.

An ACH deposit to an Erebor Bank account that matches no Autoramp isn't returned automatically. See [Cancel an Autoramp](https://dev.enterprise.moonpay.com/autoramp.md#cancel-an-autoramp).

## ACH microdeposits

When your customer links their USD account at another bank or a payroll provider, that institution often verifies it by sending two small ACH test credits. These **microdeposits** aren't a setup step for the virtual account and don't create transactions. Your customer reads the amounts and confirms them with the institution that sent them.

* **API:** `GET /api/customers/{customer_id}/microdeposits` lists the amount, currency, counterparty name, and date of each one.
* **Webhook:** `microdeposit_received` fires once for each incoming test credit. See [Webhooks](https://dev.enterprise.moonpay.com/webhooks.md).
* **Dashboard:** **Customers**, select the customer, then **Microdeposits**.

Some banks pull the test amounts back with a single ACH debit. That debit doesn't create a transaction or a `microdeposit_received` event. See [Micro-Deposits (Penny Tests)](https://dev.enterprise.moonpay.com/limits-and-minimum.md#micro-deposits-penny-tests).

## Timing

ACH, wire, FedNow, and SWIFT each settle on their own schedule. See [Settlement Times by Payment Method](https://dev.enterprise.moonpay.com/transaction-status.md#settlement-times-by-payment-method).

## Fees

A fee for the incoming bank payment comes from the Autoramp's fee profile, per rail. When it's deducted, it appears as `banking_fee` on the transaction. See [Fees on a deposit](https://dev.enterprise.moonpay.com/onramp.md#fees-on-a-deposit).

## What can go wrong

| What you see | Cause and fix |
| - | - |
| `422` `"Customer is unable to complete the action. Consult the customer abilities API"` | The USD rail isn't `Active` for this customer yet, or the customer lives in the EEA or UK. Check `fiat_deposit.usd` in the abilities |
| Autoramp stays `Authorized` | The bank hasn't opened the account yet. See [Why an Autoramp is still Authorized](https://dev.enterprise.moonpay.com/autoramp-status.md#why-an-autoramp-is-still-authorized) |
| A FedNow deposit came back | The customer isn't in the US or Canada. Ask the sender to use ACH or wire |
| No FedNow entry in `deposit_rails` | The account is at Erebor Bank, FedNow isn't enabled for your account, or you sent an `X-API-Version` before `2026-07-01` |
| An ACH deposit vanished on an Erebor Bank account | It matched no live Autoramp. Contact [support](https://dev.enterprise.moonpay.com/support.md) to recover it |

## Sandbox

Approve the Autoramp with `PUT /api/sandbox/autoramp/{id}` and simulate a deposit with `POST /api/sandbox/transaction`. See [Test the full flow in Sandbox](https://dev.enterprise.moonpay.com/onramp.md#test-the-full-flow-in-sandbox).