Create an internal transfer

This endpoint is used to facilitate internal transfers. You can transfer both fiat and crypto funds.

The transfer can be initiated according to the following scenarios:

Between a partner and a customer
Between customers of the same partner

Initiate a transfer

Create a transfer by sending the POST /payment/v2/transfers request with the following body parameters:

{
  "reference": "REF558628",
  "walletId": "a:25032550863140:zKwR3P9:1",
  "amount": 111,
  "currency": "USD",
  "beneficiary": {
    "walletId": "a:25021926815866:4jlPfFg:1",
  },
  "metadata": {
    "memberId": "987654321"
  }
}

For the detailed description of fields, see the API Reference.

To check the status of the transfer and know when it's completed successfully or failed, you can

Listen to the transfer webhook.
Send the GET /payment/v2/transfers/{transferId} request.

In the successful response, you receive the details on the transfer and its status.

{
  "id": "ae29acc3-c54a-11f0-90b6-21c3f364ff25",
  "reference": "REF558628",
  "status": "COMPLETED",
  "type": "payment:transfer",
  "method": "BOOK",
  "fees": {
    "processingFee": {
      "amount": 0,
      "currency": "USD"
    }
  },
  "originator": {
    "amount": 1.11,
    "currency": "USD",
    "entity": {
      "legalName": "3Com",
      "type": "COMPANY"
    },
    "walletId": "a:25032550863140:zKwR3P9:1"
  },
  "beneficiary": {
    "amount": 1.11,
    "currency": "USD",
    "entity": {
      "legalName": "4COM",
      "type": "COMPANY"
    },
    "walletId": "a:25021926815866:4jlPfFg:1"
  },
  "metadata": {
    "memberId": "987654321"
  },
  "createdAt": "2025-11-19T13:21:38.870144Z",
  "updatedAt": "2025-11-19T13:21:38.870144Z",
}

Transfer webhook

You can listen to this webhook to get notified when the status of the transfer changes. See the Transfer webhook documentation for more details.

Initiate a transfer​

Transfer webhook​

Initiate a transfer

Transfer webhook