BVbvnk
Internal Transfers

Create internal transfer

Changed on

Creates an internal transfer between wallets with optional currency conversion.

Supports two conversion types:

  • QUOTE: Returns a firm rate that requires client acceptance before settlement. The transfer is held in PENDING_QUOTE_ACCEPTANCE state until the client accepts the quote via the actions endpoint.

  • AUTO_CONVERSION: Automatically converts funds at the market rate without requiring quote acceptance. Only fixed debit is supported.

For same-asset transfers (originator and beneficiary currencies match), omit the conversion object.

To preview a conversion transfer without creating it, use the POST /payment/v3/transfers/dry-run endpoint instead. It returns the rate, spread, fees, and converted amounts without persisting a transfer or moving any funds.

post/payment/v3/transfers

Request

Headers

Idempotency-Keystring uuid required
Example:1e74002e-74a1-48fd-b707-147c3187a3e1

Client-generated unique identifier for the request in UUID format. Ensures that retried requests are not processed more than once.

Request body

referencestring required

Partner-supplied reference for the transfer tracking.

metadataMetadata

Custom metadata key-value pairs. Structure: key: value. Restrictions:

  • Maximum five keys.

  • Each key maximum length 50 characters.

  • Each value maximum length 100 characters.

  • Keys and values must be simple strings.

Example request

{
  "reference": "treasury-123",
  "originator": {
    "walletId": "a:25072267284363:kd3mRMO:1"
  },
  "beneficiary": {
    "walletId": "a:25072267284363:kd3mRMO:2"
  },
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  }
}

Response

Transfer created successfully

idstring uuid required

Unique transfer identifier.

referencestring required

Transfer reference provided in the request.

type'payment:transfer' required

Payment type constant for transfers.

status'PROCESSING' | 'PENDING_QUOTE_ACCEPTANCE' | 'EXPIRED' | 'COMPLETED' | 'FAILED' required

Current transfer status.

metadataMetadata

Custom metadata key-value pairs. Structure: key: value. Restrictions:

  • Maximum five keys.

  • Each key maximum length 50 characters.

  • Each value maximum length 100 characters.

  • Keys and values must be simple strings.

expiresAtstring date-time

Transfer expiration timestamp. Unaccepted quote transfers expire 24 hours after creation.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

method'BOOK'

Transfer method.

Example response

{
  "type": "payment:transfer",
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  },
  "fees": {
    "processingFee": {
      "amount": 100.5,
      "currency": "USD"
    }
  },
  "trackingDetails": [
    {
      "externalTransactionId": "123e4567-e89b-12d3-a456-426614174000",
      "imad": "20260304ABCDXXXX012345",
      "omad": "20260304QMQP021000080",
      "traceNumber": "021000080123456",
      "uetr": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "method": "BOOK"
}

Changes