Create an Internal Transfer

This endpoint is used to facilitate internal transfers.

The transfer can be initiated according to the following scenarios:

  • Between Embedded Partner and an Embedded Partner Customer
  • Between Embedded Partner Customers of the same Embedded Partner

📘

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.

To create a transfer, send the POST /transfers request with the following body parameters:

{
  "walletId": "a:24092328494070:G5i4XZ9:1",
  "amount": {
    "value": 1200,
    "currency": "USD"
  },
  "paymentReference": "Payment for supplier #67890",
  "instruction": {
    "type": "FIAT",
    "beneficiaryWalletId": "a:87333266494070:G5i9AT9:1",
  },
  "metadata": {
    "field1": "field1 value",
    "field2": "field2 value"
  }
}

Attribute

Required

Description

walletId

Yes

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

amount

Yes

Object containing value and currency for the transfer.

amount.value

Yes

The amount to be transferred out in the specified currency.

amount.currency

Yes

The currency in which the transfer will be made.

paymentReference

Yes

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

instruction

Yes

Contains information about the transfer instruction.

instruction. type

Yes

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

instruction. beneficiaryWalletId

Yes

Contains the walletId where the transfer should be made to.

metadata

No

Metadata related to the transaction.

In the successful response, you receive transfer details:

{
  "transactionReference": "123e4567-e89b-12d3-a456-426614175680",
  "fee": {
    "value": 1200,
    "currency": "USD"
  }
}

Attribute

Description

transactionReference

Unique reference identifier for the transaction (UUID).

fee

Contains information about the fees related to the transfer.

fee. value

The value of the fee.

fee. currency

The currency of the fee.


What’s Next

After making a transfer, you can check its status.