---
title: "Create a Transfer"
method: POST
path: "/v2/transfer"
---

# Create a Transfer

`POST /v2/transfer`

Create a new transfer.

## Request body

- union
  - object
    - `customer` string, required — The customer's ID.
    - `quoteId` string, required — The quote ID from a previously created quote. The transfer uses the locked exchange rate, currency, and network from the quote.
    - `externalId` string — Integrator-defined external reference. The value is not stored as unique.
    - `source` object, required
      - `type` 'bank_account' | 'wallet', required — The payment instrument type: wallet or bank_account.
      - `id` string, required — The payment instrument ID (wallet or bank account).
    - `destination` object, required
      - `type` 'bank_account' | 'wallet', required — The payment instrument type: wallet or bank_account.
      - `id` string, required — The payment instrument ID (wallet or bank account).
    - `paymentReason` 'personal' | 'investment' | 'real_estate' | 'tax' | 'loan' | 'bills' | 'reimbursement' | 'professional_services' | 'family_support' | 'education' | 'rent' | 'donation' | 'gift' | 'insurance' | 'medical' | 'savings' | 'travel' | 'mortgage' | 'fine' | 'dividend' | 'agriculture' | 'import_export' | 'art' | 'other' — The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`).
    - `paymentDescription` string — A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters.
    - `documentId` string — ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered.
  - object — Standard floating-rate transfer. For BRL (PIX) transfers: only `polygon`, `ethereum`, `base`, and `tron` wallet networks are supported (not `sol`); `integratorFixedFee` is not allowed - use `integratorBpsFeeRate` instead. See [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current transfer limits.
    - `amount` string, required — The transfer amount in source currency. Must have exactly 2 decimal places. Transfer limits are set dynamically based on due diligence and may change over time - see [BRL/PIX transfer constraints](/concepts/transfers/overview#brlpix-transfer-constraints) for current BRL limits.
    - `customer` string, required — The customer's ID.
    - `integratorFixedFee` string — The integrator fixed fee amount in source currency. Must have exactly 2 decimal places. Not supported for BRL transfers - use integratorBpsFeeRate instead.
    - `integratorBpsFeeRate` string — The integrator BPS fee rate as an integer string (1 bps = 0.01%). This is the only fee mechanism supported for BRL transfers.
    - `externalId` string — Integrator-defined external reference. The value is not stored as unique.
    - `source` union, required
      - object — The source of an `Off-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration.
        - `type` 'wallet', required — The source type: wallet.
        - `id` string, required — The source wallet ID.
        - `currency` 'usdc' | 'usdt' | 'eurc', required — The source currency for an `Off-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
        - `network` 'sol' | 'ethereum' | 'arbitrum' | 'polygon' | 'base' | 'avalanche' | 'tron', required — The source network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - object — The source of an `On-ramp` transfer.
        - `type` 'bank_account', required — The source type: bank_account.
        - `id` string, required — The source bank account ID.
        - `currency` 'usd' | 'eur' | 'brl', required — The source currency for an `On-ramp` transfer. This should be the currency of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
        - `network` 'ach' | 'wire' | 'sepa' | 'pix' | 'swift', required — The source network of the bank account. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
    - `destination` union, required
      - object — The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration.
        - `type` 'wallet', required — The destination type: wallet.
        - `id` string, required — The destination wallet ID.
        - `currency` 'usdc' | 'usdt' | 'eurc', required — The destination currency for an `On-ramp` transfer. This should be the currency of the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
        - `network` 'sol' | 'ethereum' | 'arbitrum' | 'polygon' | 'base' | 'avalanche' | 'tron', required — The destination network of the customer's wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - object — The destination bank account for transfers.
        - `type` 'bank_account', required — The destination type: bank_account.
        - `id` string, required — The destination bank account ID.
        - `currency` 'usd' | 'eur' | 'brl', required — The destination currency: [usd, eur, brl]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
        - `achReference` string — Reference sent to the receiving institution with ACH transfers, 1-10 characters.
        - `wireMessage` string — Message sent to the receiving institution with wire transfers, 1-105 characters.
        - `sepaReference` string — Reference sent to the receiving institution with SEPA transfers, 6-140 characters.
        - `network` 'ach' | 'wire' | 'sepa' | 'pix' | 'swift', required — The destination network: [wire, ach, achPush, achPull, achSameDay, swift, sepa, pix]. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
    - `paymentReason` 'personal' | 'investment' | 'real_estate' | 'tax' | 'loan' | 'bills' | 'reimbursement' | 'professional_services' | 'family_support' | 'education' | 'rent' | 'donation' | 'gift' | 'insurance' | 'medical' | 'savings' | 'travel' | 'mortgage' | 'fine' | 'dividend' | 'agriculture' | 'import_export' | 'art' | 'other' — The reason for the payment. Required for SWIFT transfers, BRL transfers, and for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`).
    - `paymentDescription` string — A free-text description of the payment purpose. Required for third-party off-ramp transfers (where the destination bank account owner relationship is not `self`). Max 500 characters.
    - `documentId` string — ID of a pre-uploaded supporting document (from POST /v2/document with target `transfer`). Required for third-party transfers on certain routes. A transfer is considered third-party when the destination bank account owner is not the customer themselves (i.e. the bank account relationship is not `self`). The document should evidence the purpose of the transfer - for example, an invoice, contract, payment agreement, or proof of services rendered.

## Response `201`

- CreateTransferResponseDto
  - `id` string, required — A unique identifier for transfer.
  - `externalId` string — The external reference (not stored as unique).
  - `type` 'on_ramp' | 'off_ramp' | 'unmatched_deposit' | 'microdeposit', required — The transfer type.
  - `status` 'pendingFunding' | 'pendingReview' | 'fundsReceived' | 'processing' | 'succeeded' | 'undeliverable' | 'returned' | 'pendingRefundInformation' | 'failed' | 'canceled' | 'refunded' | 'unexpectedError' | 'failedPrecondition' | 'expired', required — The transfer status. See [Transfer Lifecycle](/concepts/transfers/lifecycle) for status definitions and transitions.
  - `statusHistory` object[], required — Timeline of status transitions for this transfer, ascending by transitionedAt.
    - `status` 'pendingFunding' | 'pendingReview' | 'fundsReceived' | 'processing' | 'succeeded' | 'undeliverable' | 'returned' | 'pendingRefundInformation' | 'failed' | 'canceled' | 'refunded' | 'unexpectedError' | 'failedPrecondition' | 'expired', required
    - `transitionedAt` string, date-time, required — ISO 8601 timestamp of when the transfer entered this status.
  - `customer` string, required — The customer ID.
  - `fees` object — Fee breakdown for the transfer. For floating-rate BRL transfers, this is omitted until settlement is complete.
    - `integratorFee` object, required — The integrator fee, this is the portion of the fee that the API integrator will receive.
      - `fixedAmount` string, required — The fixed amount of the fee.
      - `bpsRate` string, required — The BPS rate of the fee.
      - `bpsAmount` string, required — The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount.
      - `totalAmount` string, required — The total amount of the fee applied to the source amount.
      - `currency` 'usdc' | 'usdt' | 'eurc' | 'usd' | 'eur' | 'brl', required — The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
    - `platformFee` object, required — The platform fee, this is the portion of the fee that Sphere will receive.
      - `fixedAmount` string, required — The fixed amount of the fee.
      - `bpsRate` string, required — The BPS rate of the fee.
      - `bpsAmount` string, required — The dollar amount derived from the BPS rate. Equal to totalAmount minus fixedAmount.
      - `totalAmount` string, required — The total amount of the fee applied to the source amount.
      - `currency` 'usdc' | 'usdt' | 'eurc' | 'usd' | 'eur' | 'brl', required — The currency of the fee. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
  - `source` union, required
    - object — The source of an on ramp transfer.
      - `id` string, required — The source bank account ID.
      - `type` 'bank_account', required — The source account type.
      - `currency` 'usd' | 'eur' | 'brl', required — The source bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `network` 'ach' | 'wire' | 'sepa' | 'pix' | 'swift', required — The source bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `amount` string, required — The source amount being transferred out of the source bank account.
      - `wireMessage` string — The message included with the wire transfer.
      - `achReference` string — The ACH reference string.
      - `sepaReference` string — The SEPA reference string.
    - object — The source of an off ramp transfer. See [Wallets](/concepts/transfers/wallets) for registration.
      - `id` string, required — The source wallet ID.
      - `type` 'wallet', required — The source type.
      - `currency` 'usdc' | 'usdt' | 'eurc', required — The source wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `network` 'sol' | 'fogo' | 'ethereum' | 'arbitrum' | 'polygon' | 'base' | 'avalanche' | 'sui' | 'noble' | 'sei' | 'tron' | 'starknet' | 'aptos' | 'hyperliquid', required — The source wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `amount` string, required — The source amount being transferred out of the source wallet.
  - `destination` union, required
    - object — The destination of an `On-ramp` transfer. See [Wallets](/concepts/transfers/wallets) for registration.
      - `id` string, required — The destination wallet ID.
      - `type` 'wallet', required — The destination wallet type.
      - `currency` 'usdc' | 'usdt' | 'eurc', required — The destination wallet currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `network` 'sol' | 'fogo' | 'ethereum' | 'arbitrum' | 'polygon' | 'base' | 'avalanche' | 'sui' | 'noble' | 'sei' | 'tron' | 'starknet' | 'aptos' | 'hyperliquid', required — The destination wallet network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `amount` string
      - `exchangeRate` string — The exchange rate applied to the destination amount when converting the source amount to the destination currency.
    - object — The destination of an `Off-ramp` transfer.
      - `id` string, required — The destination bank account ID.
      - `type` 'bank_account', required — The destination account type.
      - `currency` 'usd' | 'eur' | 'brl', required — The destination bank account currency. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `network` 'ach' | 'wire' | 'sepa' | 'pix' | 'swift', required — The destination bank account network. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
      - `amount` string — The destination amount being transferred to the bank account.
      - `exchangeRate` string — The exchange rate applied to the destination amount when converting the source amount to the destination currency.
      - `wireMessage` string — The message included with the wire transfer.
      - `achReference` string — The ACH reference string.
      - `sepaReference` string — The SEPA reference string.
  - `depositAccount` union, required
    - object — The deposit bank account for an on ramp transfer.
      - `type` 'bank_account', required — The type of the deposit account.
      - `bankDetails` object, required
        - `bankName` string — The name of the bank that the source funds will be transferred to.
        - `accountHolderName` string — The name of the bank account holder that the source funds will be transferred to.
        - `accountType` 'savings' | 'checking' — The type of bank account: savings or checking.
        - `accountNumber` string — The account number of the bank account, used for wires, ACH transfers and other applicable networks.
        - `routingNumber` string — The routing number of the bank account, used for wires, ACH transfers and other applicable networks.
        - `bic` string — The BIC of the bank account, used for SEPA transfers and other applicable networks.
        - `iban` string — The IBAN of the bank account, used for SEPA transfers and other applicable networks.
        - `pixKey` string — The PIX key of the deposit bank account, used for PIX transfers.
        - `brCode` string — The PIX BR code for on-ramp payments. Encode this as a QR code for the customer to scan and pay.
        - `bankAddress` string — The address of the deposit bank account.
        - `beneficiaryAddress` string — The address of the beneficiary that will receive the funds.
        - `memo` string — The memo of the transfer. This must be provided when initiating wire, ACH and SEPA transfers. This is the memo that will be used to identify the transfer to the deposit account.
    - object — The deposit wallet for an off ramp transfer.
      - `type` 'wallet', required — The type of the deposit account.
      - `walletDetails` object, required
        - `address` string, required — The address of the wallet that the source funds will be transferred to.
        - `currency` 'usdc' | 'usdt' | 'eurc', required — The currency that should be transferred to the wallet. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
        - `network` 'sol' | 'fogo' | 'ethereum' | 'arbitrum' | 'polygon' | 'base' | 'avalanche' | 'sui' | 'noble' | 'sei' | 'tron' | 'starknet' | 'aptos' | 'hyperliquid', required — The network that the source funds will be transferred on. See [Supported Rails & Currencies](/concepts/transfers/supported-rails).
  - `quote` object — The quote used for this transfer, if any. When present, the locked exchange rate from the quote was applied to the destination amount and exchange rate.
    - `id` string, required — The unique identifier for the quote used for this transfer.
    - `expiresAt` string, date-time, required — The datetime the quote expires.
  - `updated` string, date-time, required — The last datetime the transfer was updated.
  - `created` string, date-time, required — The datetime the transfer was created.
  - `paymentReason` string — The reason for the payment. Present on BRL transfers and third-party off-ramp transfers.
  - `paymentDescription` string — A free-text description of the payment purpose. Present on third-party off-ramp transfers.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `422` — Unprocessable Entity - Validation Error

---

[API](https://skmtc.net/spherepay/apis/docs-spherepay-co.md) · [All operations](https://skmtc.net/spherepay/apis/docs-spherepay-co/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/spherepay/docs-spherepay-co/versions/4f3f5484aed3/schema)