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

# Create transfer

> Create a merchant-initiated transfer

## Overview

Create a transfer to send funds to a saved recipient or an inline destination. Transfers support both NGN bank transfers and USD ACH/wire/SWIFT transfers.

Transfers are funded from your **merchant balance**. Before creating a transfer, ensure your balance has sufficient funds. You can fund your balance in two ways:

* **Crypto deposits** — send stablecoins to your [merchant funding](/api-reference/merchant-funding/get-merchant-funding) crypto wallet addresses.
* **NGN deposits** — transfer Naira to your permanent [merchant funding](/api-reference/merchant-funding/get-merchant-funding) NGN bank account (converted to USD at the current rate).

Funding account deposits are pooled into your **collection balance**. To use those funds for transfers or withdrawals, first move them to your **withdrawal balance** via the [balance transfer endpoint](/api-reference/merchant-balance/transfer-merchant-balance). Merchant funding deposits go directly into your withdrawal balance.

Exactly one of `recipient_id` or `destination` must be provided.

<Note>
  **Saved vs inline recipients:**

  * **Saved recipients** are created separately via `POST /v1/recipients` and referenced by `recipient_id`.
  * **Inline recipients** are created implicitly when `destination` is provided.
  * For inline USD destinations, `on_behalf_of.customer_id` is effectively required because the inline recipient-creation flow needs a customer context.
  * That customer must already be tier-2 verified; otherwise inline USD recipient creation fails.
</Note>

<Info>
  **Idempotency:** This endpoint is idempotent. Use `Idempotency-Key`; `X-Idempotency-Key` is also accepted as a fallback.
</Info>

## Authentication

<ParamField header="X-Api-Key" type="string" required>
  Your merchant API key
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  Unique idempotency key for request deduplication. `X-Idempotency-Key` is also accepted.

  **Example:** `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

## Request Body

<ParamField body="currency" type="string" required>
  Transfer currency.

  **Allowed values:** `NGN` | `USD`

  * `NGN` transfers: only `BANK_ACCOUNT` recipients.
  * `USD` transfers: only `US_BANK_ACCOUNT` or `SWIFT_BANK_ACCOUNT` recipients.
</ParamField>

<ParamField body="amount" type="string" required>
  Transfer amount as a decimal string in the target currency.

  **Example:** `50000.00`
</ParamField>

<ParamField body="reference" type="string" required>
  Merchant-provided unique reference for the transfer.

  **Example:** `txn_abc123`
</ParamField>

<ParamField body="recipient_id" type="string">
  ID of a previously saved recipient (UUID). Mutually exclusive with `destination`.

  **Example:** `750e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField body="destination" type="object">
  Inline destination details. Mutually exclusive with `recipient_id`.

  <Expandable title="destination properties">
    <ParamField body="destination.type" type="string" required>
      Destination type.

      **Allowed values:** `BANK_ACCOUNT` | `US_BANK_ACCOUNT` | `SWIFT_BANK_ACCOUNT`
    </ParamField>

    <ParamField body="destination.bank_account" type="object">
      Nigerian bank account details. Required when `destination.type` is `BANK_ACCOUNT`.

      <Expandable title="bank_account properties">
        <ParamField body="destination.bank_account.account_number" type="string" required>
          Bank account number
        </ParamField>

        <ParamField body="destination.bank_account.bank_code" type="string" required>
          Bank code (CBN code)
        </ParamField>

        <ParamField body="destination.bank_account.account_name" type="string">
          Account holder name (resolved automatically if omitted)
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="destination.us_bank_account" type="object">
      US bank account details. Required when `destination.type` is `US_BANK_ACCOUNT`.

      <Expandable title="us_bank_account properties">
        <ParamField body="destination.us_bank_account.account_owner_name" type="string" required>
          Owner of the bank account. 1-256 characters. ACH and wire transfers enforce regex constraints on this field.
        </ParamField>

        <ParamField body="destination.us_bank_account.account_number" type="string" required>
          Account number
        </ParamField>

        <ParamField body="destination.us_bank_account.routing_number" type="string" required>
          Routing number
        </ParamField>

        <ParamField body="destination.us_bank_account.bank_name" type="string" required>
          Bank name (1-256 characters)
        </ParamField>

        <ParamField body="destination.us_bank_account.account_type" type="string" required>
          **Allowed values:** `checking` | `savings`
        </ParamField>

        <ParamField body="destination.us_bank_account.payout_scheme" type="string" required>
          **Allowed values:** `ach` | `wire`
        </ParamField>

        <ParamField body="destination.us_bank_account.address" type="object" required>
          Address of the beneficiary. US addresses used to receive wires must include a street number. `country` must be an ISO 3166-1 alpha-3 code. State must be a valid ISO 3166-2 subdivision code for US addresses.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="destination.swift_bank_account" type="object">
      SWIFT bank account details. Required when `destination.type` is `SWIFT_BANK_ACCOUNT`. For individual recipients, provide `first_name` and `last_name`. For business recipients, provide `business_name`.

      <Expandable title="swift_bank_account properties">
        <ParamField body="destination.swift_bank_account.account_owner_name" type="string" required>
          Owner of the bank account. 1-256 characters. ACH and wire transfers enforce regex constraints on this field.
        </ParamField>

        <ParamField body="destination.swift_bank_account.account_owner_type" type="string" required>
          For `individual`, provide `first_name` and `last_name`. For `business`, provide `business_name`.

          **Allowed values:** `individual` | `business`
        </ParamField>

        <ParamField body="destination.swift_bank_account.account_country" type="string" required>
          ISO 3166-1 alpha-3 country code where the bank account is held (3 characters)
        </ParamField>

        <ParamField body="destination.swift_bank_account.iban" type="string" required>
          International Bank Account Number
        </ParamField>

        <ParamField body="destination.swift_bank_account.bic" type="string">
          Bank Identifier Code (optional)
        </ParamField>

        <ParamField body="destination.swift_bank_account.bank_name" type="string">
          Bank name (1-256 characters, optional)
        </ParamField>

        <ParamField body="destination.swift_bank_account.first_name" type="string">
          Required when `account_owner_type` is `individual`
        </ParamField>

        <ParamField body="destination.swift_bank_account.last_name" type="string">
          Required when `account_owner_type` is `individual`
        </ParamField>

        <ParamField body="destination.swift_bank_account.business_name" type="string">
          Required when `account_owner_type` is `business`
        </ParamField>

        <ParamField body="destination.swift_bank_account.category" type="string" required>
          The context of business operations.

          **Allowed values:** `client` | `parent_company` | `subsidiary` | `supplier`
        </ParamField>

        <ParamField body="destination.swift_bank_account.purpose_of_funds" type="array" required>
          The nature of the transactions this account will participate in. At least one value required.

          **Allowed values:** `intra_group_transfer` | `invoice_for_goods_and_services`
        </ParamField>

        <ParamField body="destination.swift_bank_account.short_business_description" type="string" required>
          How the business uses the funds.
        </ParamField>

        <ParamField body="destination.swift_bank_account.address" type="object" required>
          Address of the beneficiary. `country` must be an ISO 3166-1 alpha-3 code. US addresses used to receive wires must include a street number.
        </ParamField>

        <ParamField body="destination.swift_bank_account.bank_address" type="object" required>
          Bank address. `country` must be an ISO 3166-1 alpha-3 code.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="on_behalf_of" type="object">
  Optional metadata linking the transfer to a customer. Effectively required for inline USD destinations.

  <Expandable title="on_behalf_of properties">
    <ParamField body="on_behalf_of.customer_id" type="string" required>
      Customer ID (UUID)
    </ParamField>
  </Expandable>
</ParamField>

## Request Examples

<CodeGroup>
  ```bash cURL - NGN Bank Transfer (saved recipient) theme={null}
  curl --request POST \
    --url https://api.daya.co/v1/transfers \
    --header 'X-Api-Key: YOUR_API_KEY' \
    --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
    --header 'Content-Type: application/json' \
    --data '{
      "currency": "NGN",
      "amount": "50000.00",
      "reference": "txn_ngn_001",
      "recipient_id": "750e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```bash cURL - USD Transfer (inline US bank) theme={null}
  curl --request POST \
    --url https://api.daya.co/v1/transfers \
    --header 'X-Api-Key: YOUR_API_KEY' \
    --header 'Idempotency-Key: 660e8400-e29b-41d4-a716-446655440000' \
    --header 'Content-Type: application/json' \
    --data '{
      "currency": "USD",
      "amount": "100.00",
      "reference": "txn_usd_001",
      "on_behalf_of": {
        "customer_id": "650e8400-e29b-41d4-a716-446655440000"
      },
      "destination": {
        "type": "US_BANK_ACCOUNT",
        "us_bank_account": {
          "account_owner_name": "Jane Smith",
          "account_number": "123456789",
          "routing_number": "021000021",
          "bank_name": "Chase",
          "account_type": "checking",
          "payout_scheme": "ach",
          "address": {
            "street_line_1": "123 Main St",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "USA"
          }
        }
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string" required>
  Transfer ID (UUID)
</ResponseField>

<ResponseField name="reference" type="string" required>
  Merchant-provided reference
</ResponseField>

<ResponseField name="status" type="string" required>
  External status: `PROCESSING`, `SETTLED`, or `FAILED`
</ResponseField>

<ResponseField name="rail" type="string" required>
  Transfer rail: `NGN_BANK` or `USD_BANK`
</ResponseField>

<ResponseField name="currency" type="string" required>
  Transfer currency (`NGN` or `USD`)
</ResponseField>

<ResponseField name="amount" type="string" required>
  Transfer amount in the target currency
</ResponseField>

<ResponseField name="debit_currency" type="string" required>
  Currency debited from the merchant balance (`USD`)
</ResponseField>

<ResponseField name="debit_amount" type="string" required>
  Total amount debited from the merchant withdrawal balance, including fees.
</ResponseField>

<ResponseField name="fee" type="string" required>
  Fee amount.
</ResponseField>

<ResponseField name="rate" type="object">
  Captured exchange rate snapshot. Present for NGN transfers.

  <Expandable title="rate properties">
    <ResponseField name="rate.side" type="string">
      Rate side (e.g. `SELL`)
    </ResponseField>

    <ResponseField name="rate.value" type="string">
      Rate value
    </ResponseField>

    <ResponseField name="rate.captured_at" type="string">
      When the rate was captured (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recipient" type="object">
  Resolved recipient details
</ResponseField>

<ResponseField name="on_behalf_of" type="object">
  Customer metadata if provided
</ResponseField>

<ResponseField name="created_at" type="string" required>
  When the transfer was created (ISO 8601)
</ResponseField>

<ResponseField name="settled_at" type="string">
  When the transfer settled (ISO 8601). Null if not yet settled.
</ResponseField>

### Success Response

<ResponseExample>
  ```json 201 Created - NGN Transfer theme={null}
  {
    "id": "850e8400-e29b-41d4-a716-446655440000",
    "reference": "txn_ngn_001",
    "status": "PROCESSING",
    "rail": "NGN_BANK",
    "currency": "NGN",
    "amount": "50000.00",
    "debit_currency": "USD",
    "debit_amount": "33.07",
    "fee": "0.81",
    "rate": {
      "side": "SELL",
      "value": "1550.00",
      "captured_at": "2026-01-05T15:04:05Z"
    },
    "recipient": {
      "id": "750e8400-e29b-41d4-a716-446655440000",
      "type": "BANK_ACCOUNT",
      "bank_account": {
        "account_name": "John Doe",
        "account_number_last4": "7890",
        "bank_code": "044",
        "bank_name": "Access Bank"
      }
    },
    "on_behalf_of": null,
    "created_at": "2026-01-05T15:04:05Z",
    "settled_at": null
  }
  ```

  ```json 201 Created - USD Transfer theme={null}
  {
    "id": "950e8400-e29b-41d4-a716-446655440000",
    "reference": "txn_usd_001",
    "status": "PROCESSING",
    "rail": "USD_BANK",
    "currency": "USD",
    "amount": "100.00",
    "debit_currency": "USD",
    "debit_amount": "100.00",
    "fee": "0.00",
    "rate": null,
    "recipient": {
      "id": "860e8400-e29b-41d4-a716-446655440000",
      "type": "US_BANK_ACCOUNT",
      "us_bank_account": {
        "account_owner_name": "Jane Smith",
        "account_number_last4": "6789",
        "bank_name": "Chase",
        "account_type": "checking",
        "payout_scheme": "ach"
      }
    },
    "on_behalf_of": {
      "customer_id": "650e8400-e29b-41d4-a716-446655440000"
    },
    "created_at": "2026-01-05T15:04:05Z",
    "settled_at": null
  }
  ```
</ResponseExample>

## Notes

* A minimum effective USD debit of \$0.50 is enforced. For NGN transfers, the corresponding Naira amount varies with the effective `SELL` exchange rate.
* For NGN transfers, `amount` is the NGN sent to the recipient and `debit_amount` is the total USD debited from your withdrawal balance, including fees.
* Saved USD recipients can be reused later without resending full destination details.
* Transfers emit `transfer.*` webhooks: `transfer.created`, `transfer.processing`, `transfer.submitted`, then `transfer.completed` or `transfer.failed`. `transfer.requires_review` is sent when a transfer is flagged.