---
title: "Create internal transfer"
method: POST
path: "/payment/v1/transfers"
tags: ["Fiat Payments"]
deprecated: true
---

# Create internal transfer

`POST /payment/v1/transfers`

## Request

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

> **Deprecated.**

Create an internal Fiat transfer to an existing beneficiary wallet.

## Headers

- `X-Idempotency-Key` string, uuid, required

## Request body

- CreateTransferRequest
  - `walletId` string, required: Identifier for the debit wallet associated with the transaction.
  - `amount` Money, required
    - `value` number, float, required: Transfer amount in major currency units.
    - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code.
  - `paymentReference` string, required: Custom identifier supplied for a transaction. It is used to link a transaction to a specific customer or use case. Note that the value is visible to the beneficiary. Only whitespaces, alphanumeric characters (a-z, A-Z, 0-9), commas (,) and periods (.).
  - `instruction` object, required
    - `type` 'FIAT', required: The type of the instruction. Currently only 'FIAT' is supported.
    - `beneficiaryWalletId` string, required: Identifier for the credit wallet associated with the transaction.
  - `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 `200`

Created

- CreateTransferResponse
  - `transactionReference` string, uuid, required: Unique identifier for the transaction.
  - `fee` Money, required
    - `value` number, float, required: Transfer amount in major currency units.
    - `currency` 'USD' | 'EUR' | 'GBP', required: Three-letter ISO-4217 currency code.

## Other responses

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

## Changes

- **2026-06-16** `97d6c0d2fe2e`: 2 breaking, 2 warning, 2 info
  - 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
  - removed the optional property `details/errors/requestBody` from the response with the `403` status
  - …2 more

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v1/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)