BVbvnk
Internal Transfers

Preview internal transfer

Changed on

Previews an internal transfer without creating it. BVNK calculates and returns conversion details, including exchange rate, spread, fees, and converted amounts, but does not initiate a transfer or move funds. Use this feature to show your customer the exact rate and amounts before confirming a transfer.

It supports both QUOTE and AUTO_CONVERSION types. Same-asset transfers, where the originator and beneficiary currencies match, are not supported.

The request and response formats are identical to POST /payment/v3/transfers. When you are ready to proceed, send the same request to that endpoint.

post/payment/v3/transfers/dry-run

Request

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

Preview generated successfully. The response has the same shape as a created transfer, but nothing is persisted: don't use its id or conversion.digest with other endpoints.

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