---
title: "Create internal transfer"
method: POST
path: "/payment/v2/transfers"
tags: ["Fiat Payments", "Crypto Payments"]
---

# Create internal transfer

`POST /payment/v2/transfers`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/payment/v2/transfers`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/payment/v2/transfers/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates an internal stablecoin and fiat transfer between customer's and partner's wallets.

Payment combinations:

- Crypto to crypto

- Fiat to fiat

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- TransferRequestV2
  - `walletId` string, required: Identifier for your debit wallet associated with the transaction.
  - `amount` number, float, required: Transfer amount in fiat and crypto currency units.
  - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and crypto currencies.
  - `reference` string, required: Internal identifier that is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment.
  - `beneficiary` object, required: Beneficiary information for the transfer. For internal transfers, only the wallet ID is required.
    - `walletId` string, required: Identifier for the beneficiary wallet that will receive the transfer. The wallet to which funds will be credited.
  - `metadata` Metadata: 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.

## Response `201`

Transfer created successfully

- TransferResponseV2
  - `id` string, uuid, required: Unique transfer identifier.
  - `reference` string, required: Transfer unique reference that you must provide.
  - `type` 'payment:transfer', required: Payment type constant for transfers.
  - `status` 'PROCESSING' | 'COMPLETED' | 'FAILED', required: Current transfer status. More statuses may be added in future releases.
  - `method` 'BOOK', required: Transfer method.
  - `fees` object, required
    - `processingFee` MoneyFeeV2
      - `amount` number, required: Fee amount in fiat or crypto currency units.
      - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and cryptocurrencies.
  - `originator` object, required: Originator information for the transfer.
    - `amount` number, float, required: Amount of the transfer.
    - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and crypto currencies.
    - `walletId` string, required: The ID of the originator's wallet associated with the transfer.
    - `entity` union, required
      - TransferIndividual
        - `type` 'INDIVIDUAL', required: Entity type
        - `firstName` string, required: First name
        - `lastName` string, required: Last name
      - TransferCompany
        - `type` 'COMPANY': Entity type
        - `legalName` string, required: Legal company name
  - `beneficiary` object, required: Beneficiary information for the transfer.
    - `amount` number, float, required: Amount credited to the beneficiary wallet.
    - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and crypto currencies.
    - `walletId` string, required: The ID of the beneficiary's wallet associated with the transfer.
    - `entity` union
      - TransferIndividual
        - `type` 'INDIVIDUAL', required: Entity type
        - `firstName` string, required: First name
        - `lastName` string, required: Last name
      - TransferCompany
        - `type` 'COMPANY': Entity type
        - `legalName` string, required: Legal company name
  - `metadata` Metadata: 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.
  - `createdAt` string, date-time, required: Creation timestamp.
  - `updatedAt` string, date-time, required: Last update timestamp.

## Other responses

- `400`: Bad request
- `403`: Forbidden

## Changes

- **2026-06-16** `97d6c0d2fe2e`: 3 breaking, 2 warning, 2 info
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `3` to `36`
  - the `details/errors` response's property type changed from `object` to `array` for status `400`
  - the `details/errors` response's property type changed from `object` to `array` for status `403`
  - removed the optional property `details/errors/requestBody` from the response with the `400` status
  - …3 more

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v2/transfers/post.md)

---

[API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)