Create an Internal Transfer

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 Idempotency-Key header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.

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

{
  "reference": "REF558628",
  "walletId": "a:25032550863140:zKwR3P9:1",
  "amount": 1.11,
  "currency": "USD",
  "method": "BOOK",
  "beneficiary": {
    "walletId": "a:25021926815866:4jlPfFg:1",
    "entity": {
      "type": "COMPANY",
      "legalName": "4Com",
      "relationshipType": "SELF_OWNED"
    }
  },
  "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",
  "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",
  "type": "payment:transfer",
  "method": "BOOK"
}