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

# United States overview

> Everything to integrate USD payins, payouts and cross-border payments, on one page.

The United States runs payins, payouts and cross-border payments in USD. This page takes you through a US integration from start to finish. Each step links to the full guide when you need more detail.

## At a glance

| | United States |
| - | - |
| Fiat | USD |
| Payin methods | `ACH_PULL`, `WIRE`, `RTP` |
| Payout rails (`bank_account_type`) | `ACH_PUSH` (default), `RTP`, `DOMESTIC_WIRE`, `FEDWIRE`, `WIRE` |
| Cross-border | A standard payout with `transfer_purpose` and `is_self_transfer: false` |
| Payin reference | `transaction_reference_id`. Optional |
| KYC | [KYC SDK](/guides/customers/kyc-sdk) for payin customers. [Payout-only onboarding](/guides/customers/payout-only-onboarding) for payout beneficiaries |

## 1. Payins (USD to stablecoins)

<Steps>
  <Step title="Create the customer" icon="user-plus">
    ```json POST /cms/api/v1/customer/create theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "client_reference_id": "user-001",
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "dob": "1990-01-15",
      "alpha_3_country_code": "USA"
    }
    ```

    US customers need `dob` (`YYYY-MM-DD`). Save the returned `id` as `customer_id`.
  </Step>

  <Step title="Verify identity" icon="id-card">
    ```json POST /cms/api/v1/kyc/generate-link theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "redirect_url": "https://yourapp.com/kyc/return"
    }
    ```

    Redirect the user to the returned `url`, then wait for the `CUSTOMER` webhook with `VERIFIED`. See [KYC SDK](/guides/customers/kyc-sdk).
  </Step>

  <Step title="Link a bank account (ACH_PULL only)" icon="building-columns">
    `ACH_PULL` debits the customer's own bank account, so the customer links it first:

    ```json POST /cms/api/v1/bank/generate-link theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "redirect_url": "https://yourapp.com/bank/return"
    }
    ```

    Open the returned `widget_url`. The customer signs in to their bank, picks the account and returns to `redirect_url`. Poll [`GET /cms/api/v1/bank/list/{customer_id}`](/api-reference-exchange/endpoint/bank/list-\{customer_id}) until the account under `accounts` is `VERIFIED`; no `BANK` webhook is sent. Save its `id`: an `ACH_PULL` quotation needs it as `bank_id`.

    <Note>
      In sandbox, call [Mock Bank Verification](/api-reference-exchange/endpoint/bank/mock-bank-verification) with the `customer_id`, `bank_status: "VERIFIED"` and no `bank_id`. It creates a linked test account.
    </Note>
  </Step>

  <Step title="Create a quotation" icon="file-invoice-dollar">
    ```json POST /pis/api/v1/payin/quotation theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "asset": "USDC",
      "fiat": "USD",
      "network": "polygon",
      "payment_method": "WIRE",
      "sending_amount": "1000",
      "risk_parameters": {
        "ip_address": "203.0.113.10",
        "device_id": "device-123",
        "suspicious_activity_report": false,
        "law_enforcement_agency_report": false
      }
    }
    ```

    `payment_method` is `ACH_PULL`, `WIRE` or `RTP`. For `ACH_PULL`, also send `bank_id`: the linked account from the previous step. For every method except `ACH_PULL`, the response has `deposit_instructions`: `account_number`, `routing_number`, `bank_name`, `bank_address`, `account_holder_name` and a `narrative` to include with the transfer.
  </Step>

  <Step title="Collect the USD" icon="money-bill-wave">
    The user pays the exact `sending_amount` from a bank account in their own name, before `expiry_time`. `ACH_PULL` debits the bank account the customer linked in the previous step, so the user doesn't make a transfer.
  </Step>

  <Step title="Initiate the payin" icon="arrow-down-to-line">
    ```json POST /pis/api/v1/payin/initiate theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "quotation_id": "da43453c-f854-42ac-9a1e-619b37060bbc",
      "customer_id": "075986f3-282b-4555-bfcd-fad973e32596",
      "client_reference_id": "payin-001"
    }
    ```

    `transaction_reference_id` is optional. Add it if the user has the bank's transfer reference.
  </Step>

  <Step title="Credit on SUCCESS" icon="bell">
    The `PAYIN` webhook moves to `SUCCESS` with the `transaction_hash`. Credit the user only then. See [Payins](/guides/payments/payins#6-track-the-result) for every status.
  </Step>
</Steps>

## 2. Payouts (stablecoins to USD)

US beneficiaries skip full KYC. Onboard them with payout-only onboarding, which must be enabled for your organization.

<Steps>
  <Step title="Create the beneficiary" icon="user-plus">
    ```json POST /cms/api/v1/customer/payout/create theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    { "client_reference_id": "beneficiary-001", "full_name": "John Smith", "alpha_3_country_code": "USA" }
    ```

    Save the returned `id` as `customer_id`.
  </Step>

  <Step title="Create the KYC profile" icon="id-card">
    ```json POST /cms/api/v1/kyc/payout/add-kyc-data theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    { "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4" }
    ```
  </Step>

  <Step title="Add the address" icon="location-dot">
    ```json POST /cms/api/v1/kyc/payout/add-sender-kyc-data theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "client_reference_id": "beneficiary-001",
      "country_code": "USA",
      "street": "350 Fifth Avenue"
    }
    ```

    The US needs only `street`.
  </Step>

  <Step title="Add the bank account" icon="building-columns">
    ```json POST /cms/api/v1/bank/payout/create theme={"theme":{"light":"css-variables","dark":"css-variables"}}
    {
      "customer_id": "84737c7d-7b62-4204-80d6-80f6ecb3ceb4",
      "bank_account_type": "ACH_PUSH",
      "identifiers": {
        "account_holder_name": "John Smith",
        "bank_name": "Chase",
        "account_number": "123456789012",
        "routing_number": "021000021"
      }
    }
    ```

    Save the returned `id` as `bank_id`. The table below lists the fields for each rail.
  </Step>

  <Step title="Quote, fund and initiate" icon="paper-plane">
    Create a [payout quotation](/guides/payments/payouts#3-create-a-quotation) with `customer_id`, `bank_id`, `fiat: "usd"` and the `payment_method` that [`GET /payout/configuration`](/api-reference-exchange/endpoint/payout/config/configuration) lists for USD. Send the crypto to `wallet_address`, then initiate with the `transaction_hash`. Paying from a balance instead? See [Prefunded payouts](/guides/payments/prefunded-payouts).
  </Step>
</Steps>

| Rail (`bank_account_type`) | `identifiers` | Notes |
| - | - | - |
| `ACH_PUSH` (default) | `account_holder_name`, `bank_name`, `account_number`, `routing_number` | `routing_number` is the ABA routing number |
| `RTP` | `account_holder_name`, `bank_name`, `account_number`, `routing_number` | |
| `DOMESTIC_WIRE` | `account_holder_name`, `bank_name`, `account_number`, `routing_number` | |
| `FEDWIRE` | `account_holder_name`, `bank_name`, `account_number`, `routing_number` | |
| `WIRE` | `account_holder_name`, `bank_name`, `account_number`, `swift_code` | `swift_code` is the SWIFT/BIC |

## 3. Cross-border payments

A cross-border payment to the US is a standard payout, funded with USDC you onramped elsewhere or already hold. When you add the bank account, send a `transfer_purpose`, such as `FAMILY_MAINTENANCE`, and `is_self_transfer: false`. Without them, the payout defaults to `TRANSFER_TO_OWN_ACCOUNT`. See [Cross-border payments](/guides/payments/cross-border-payments#purpose-of-the-transfer).

## 4. Test in sandbox

| What | How |
| - | - |
| Verify the customer | [Mock KYC Status](/api-reference-exchange/endpoint/kyc/mock-kyc-status) |
| Payin | Initiate without a reference, then [Mock Payin Status](/api-reference-exchange/endpoint/payin/order/mock-payin-status) |
| Payout | Quote on `sepolia`, send testnet stablecoins, then [Mock Payout Status](/api-reference-exchange/endpoint/payout/order/mock-payout-status) |

<CardGroup cols={2}>
  <Card title="Payins" icon="arrow-down-to-line" href="/guides/payments/payins">
    Quotation, deposit instructions and every payin status.
  </Card>

  <Card title="Payout-only onboarding" icon="user-plus" href="/guides/customers/payout-only-onboarding">
    The fields and rules for every payout market.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.