Create an internal transfer

• Embedded model
• Crypto
• Fiat
• Stablecoin

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

note

This capability is only available as part of the Virtual Account use cases and cannot be used separately.

Initiate a transfer

1. 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.

2. 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.