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

# Initiate a transfer

> Creates a merchant-principal transfer from a valid quote. Balance-funded transfers reserve immediately; bank/crypto-funded transfers return intent-specific funding instructions and wait for an exact receipt. The request contract has no customer or on-behalf-of field.



## OpenAPI

````yaml /openapi.json post /v1/transfers
openapi: 3.0.3
info:
  contact:
    email: support@yara.cash
    name: Yara API Support
  description: >-
    Merchant-facing wallets/address-as-a-service API for creating merchant
    receive addresses, inspecting balances, quoting transfers, and initiating
    payouts to whitelisted recipients.

    Public endpoints are for external integrators. Dashboard endpoints are
    gateway-to-environment surfaces protected by the external API gateway.
    Internal endpoints are platform/system surfaces protected by an internal
    token.
  license:
    name: Proprietary
  title: Yara External API - Public API
  version: '1.0'
servers:
  - url: https://api.yara.cash
security: []
paths:
  /v1/transfers:
    post:
      tags:
        - public.transfers
      summary: Initiate a transfer
      description: >-
        Creates a merchant-principal transfer from a valid quote. Balance-funded
        transfers reserve immediately; bank/crypto-funded transfers return
        intent-specific funding instructions and wait for an exact receipt. The
        request contract has no customer or on-behalf-of field.
      parameters:
        - description: Idempotency key
          in: header
          name: X-Idempotency-Key
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferCreateRequest'
        description: Transfer creation request
        required: true
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TransferCreateRequest:
      properties:
        quote_id:
          example: 0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3
          type: string
        reference:
          example: merchant-transfer-001
          type: string
      type: object
    TransferResponse:
      properties:
        data:
          $ref: '#/components/schemas/Transfer'
      type: object
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
    Transfer:
      properties:
        created_at:
          example: '2026-06-16T03:00:00Z'
          type: string
        destination_amount:
          $ref: '#/components/schemas/TransferAmount'
        destination_rail:
          example: US_BANK_ACCOUNT
          type: string
        funding:
          $ref: '#/components/schemas/TransferFundingIntent'
        funding_method:
          example: BALANCE
          type: string
        funding_receipts:
          items:
            $ref: '#/components/schemas/TransferFundingReceipt'
          type: array
        id:
          example: 76179a66-8695-47fd-bca4-310eaa816077
          type: string
        quote_id:
          example: 0e0f7b9c-f47b-4f42-b56e-991b8f7a1cb3
          type: string
        recipient_id:
          example: 3bf24579-a35a-4ba9-a936-5df9c1d809f9
          type: string
        reference:
          example: merchant-transfer-001
          type: string
        status:
          example: RESERVED
          type: string
        total_debit:
          $ref: '#/components/schemas/TransferAmount'
        transfer_fee:
          $ref: '#/components/schemas/TransferAmount'
        updated_at:
          example: '2026-06-16T03:01:00Z'
          type: string
      type: object
    ErrorBody:
      properties:
        code:
          example: validation_error
          type: string
        message:
          example: invalid JSON body
          type: string
      type: object
    TransferAmount:
      properties:
        asset:
          example: USDC
          type: string
        currency:
          example: USD
          type: string
        network:
          example: BASE
          type: string
        value:
          example: '100.00'
          type: string
      type: object
    TransferFundingIntent:
      properties:
        bank_transfer:
          $ref: '#/components/schemas/TransferBankFundingInstructions'
        crypto_deposit:
          $ref: '#/components/schemas/TransferCryptoFundingInstructions'
        expires_at:
          type: string
        flag:
          $ref: '#/components/schemas/TransferFundingFlag'
        id:
          type: string
        method:
          example: BANK_TRANSFER
          type: string
        required_amount:
          $ref: '#/components/schemas/TransferAmount'
        status:
          example: PENDING
          type: string
      type: object
    TransferFundingReceipt:
      properties:
        expected_amount:
          $ref: '#/components/schemas/TransferAmount'
        fee_usd:
          $ref: '#/components/schemas/TransferAmount'
        flag:
          $ref: '#/components/schemas/TransferFundingFlag'
        gross_usd:
          $ref: '#/components/schemas/TransferAmount'
        id:
          type: string
        method:
          example: CRYPTO_DEPOSIT
          type: string
        net_usd:
          $ref: '#/components/schemas/TransferAmount'
        provider_transaction_id:
          type: string
        received_amount:
          $ref: '#/components/schemas/TransferAmount'
        received_at:
          type: string
        status:
          example: CREDITED
          type: string
        variance_amount:
          $ref: '#/components/schemas/TransferAmount'
      type: object
    TransferBankFundingInstructions:
      properties:
        account_name:
          example: Yara
          type: string
        account_number:
          example: '1234567890'
          type: string
        bank_code:
          example: '035'
          type: string
        bank_name:
          example: Wema Bank
          type: string
        narration:
          example: funding-76179a66869547fdbca4310eaa816077
          type: string
        reference:
          example: funding-76179a66869547fdbca4310eaa816077
          type: string
      type: object
    TransferCryptoFundingInstructions:
      properties:
        address:
          example: '0x1234'
          type: string
        asset:
          example: USDC
          type: string
        memo:
          type: string
        network:
          example: BASE
          type: string
        reference:
          example: funding-76179a66869547fdbca4310eaa816077
          type: string
      type: object
    TransferFundingFlag:
      properties:
        code:
          example: AMOUNT_MISMATCH
          type: string
        message:
          example: Funding amount does not match the expected amount
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: 'Public merchant API key. You can also send Authorization: ApiKey <key>.'
      in: header
      name: X-Yara-API-Key
      type: apiKey

````