Create a transfer

Move funds from one of your wallets to another wallet in your organization, instantly.

POST/v1/wallets/:id/transfer
Idempotenttransfer

Moves funds from this wallet to another wallet in your organization. Requires the transfer scope and an Idempotency-Key. The path :id is the source wallet.

Try it, for realPOST /wallets/:id/transferscope: transfer

Test keys only. Never paste a live key. Your key is stored only in this browser (localStorage) and sent only to the same-origin playground proxy.

›Equivalent request (curl / TypeScript)
curl
curl -X POST https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/transfer \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: …" \
  -d '{"destinationWalletId":"acuinf771204938810wlt","amount":500000,"description":"Order #8842 split"}'
TypeScript
const res = await fetch("https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/transfer", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACUTE_TEST_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"destinationWalletId":"acuinf771204938810wlt","amount":500000,"description":"Order #8842 split"}),
});
const { data, meta } = await res.json();

# transfer ₦5,000 between wallets
curl -X POST https://sandbox.api.acute.network/v1/wallets/acuinf483920175566wlt/transfer \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f2c8a1e-7b34-4d5a-9e1f-22c0d8b6a4e5" \
  -d '{
    "destinationWalletId": "acuinf771204938810wlt",
    "amount": 500000,
    "description": "Order #8842 split"
  }'
{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "acuinf905172634408trf",
    "sourceWalletId": "acuinf483920175566wlt",
    "destinationWalletId": "acuinf771204938810wlt",
    "amount": 500000,
    "fee": 7500,
    "status": "completed",
    "description": "Order #8842 split",
    "currency": "NGN",
    "createdAt": "2026-06-24T09:20:11.882Z"
  },
  "meta": { "requestId": "req_4f9c2a7e1b0d8c3a5e6f10a2" }
}

Transfers settle synchronously

The 201 already carries status: "completed". There is no webhook to wait on. The transfers guide covers the ledger postings.

idstringpathrequired

The source wallet reference.

destinationWalletIdstringbodyrequired

The destination wallet reference. Must differ from the source; a self-transfer returns 422 (TRANSFER_SELF).

amountinteger (kobo)bodyrequired

Amount to move, in kobo. Positive integer.

descriptionstringbodyoptional

An optional note stored on the transfer.

TransferResponseData.

idstringrequired

The transfer reference (acuinf…trf).

sourceWalletIdstringrequired

The source wallet reference.

destinationWalletIdstringrequired

The destination wallet reference.

amountnumber (kobo)required

The amount moved.

feenumber (kobo)required

The transfer fee charged to the source. See fees.

status'completed' | 'failed'required

Transfers settle synchronously; completed on success.

descriptionstring | nullrequired

The note, or null.

currencystringrequired

The currency (NGN).

createdAtstringrequired

ISO-8601 timestamp.