Step 3: Creating a Transfer

This endpoint is used to facilitate internal transfers. They can be defined by a few scenarios:

The movement of funds between a BVNK user to their customer, their customer to the BVNK user, and from a BVNK user's customer to another customer of the BVNK user.


🚧

Early Access

Please note that this endpoint is currently in early access, and it may undergo changes as we continue to improve and refine the functionality.

📘

Idempotency supported endpoint

This means you can retry a request without worrying about it being processed multiple times.

To use this feature, add the X-Idempotency-Key header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.


Request

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/payment/v1/transfers
SandboxPOST https://api.sandbox.bvnk.com/payment/v1/transfers
curl --request POST \
     --url 'https://api.sandbox.bvnk.com/payment/v1/transfers' \
     --header 'X-Idempotency-Key: f21b904d-8edb-46b0-b049-e611b1994e1d' \
     --header 'Authorization: Hawk id="B9jnE1U8eLblzHtNeJZRxfcq03CQKcmcP9FOrACMzXb1HfrxrePWsTfuP70JNns9", ts="1633010032", nonce="guGXrD", mac="uKeg+w1qXqzaF/8mOQGv8Y9IlRxyxTT+iINLe03EQ60="' \
     --header 'Content-Type: application/json' \
     --data '{
  "walletId": "a:24092328494070:G5i4XZ9:1",
  "amount": {
    "value": 700,
    "currency": "GBP"
  },
  "paymentReference": "Payment for invoice #12345",
  "instruction": {
    "type": "FIAT",
    "beneficiaryWalletId": "a:87333266494070:G5i9AT9:1",
    "beneficiaryAccountReference": "123e4567-e89b-12d3-a456-426614174000"
  },
  "metadata": {
    "field1": "field1 value",
    "field2": "field2 value"
  }
}'

Attribute

Type

Required

Description

walletId

String

Yes

The unique identifier for the wallet from which the transfer will be made.

amount

Object

Yes

Object containing value and currency for the transfer.

amount.value

Number

Yes

The amount to be transferred out in the specified currency.

amount.currency

String

Yes

The currency in which the transfer will be made.

paymentReference

String

Yes

A reference string for the transfer, often used for invoicing or tracking purposes.

instruction

Object

Yes

Contains information about the transfer instruction.

instruction.
type

String

Yes

The type of instruction, either "FIAT" or "CRYPTO".

instruction.
beneficiaryWalletId

String

Yes

Contains the walletId where the transfer should be made to.

instruction.
beneficiaryAccountReference

String

Yes

Contains the account reference where the transfer should be made to.

metadata

Object

No

Metadata related to the transaction.

Successful response

{
  "transactionReference": "123e4567-e89b-12d3-a456-426614174000",
  "fee": {
    "value": 700,
    "currency": "GBP"
  }
}

Response Header: LOCATION: https://api.sanbox.bvnk.com/payment/v1/transfers/{transaction_id}

Response codes

Response codeStatusDescription
200CreatedRequest has been created successfully.
400Bad requestValidation errors.

Attribute

Type

Description

transactionReference

String

Unique reference identifier for the transaction (UUID).

fee

Object

Contains information about the fees related to the transfer.

fee.
value

Number

The value of the fee.

fee.
currency

String

The currency of the fee.