Create an account transfer

Moves funds between two accounts belonging to the same entity. A same-currency transfer is priced using the standard fee schedule for the source account; a cross-currency transfer must supply a quote_id obtained beforehand from the currency conversion quotes API, which is consumed (single-use) by this call and pins the exchange rate, destination amount, and fee for the transfer.

If the entity has an active maker-checker approver group configured for account transfers that matches the source account/amount, the transfer is created in a pending-approval state and queued for approval instead of being processed immediately — no quote is consumed and no ledger postings occur until the transfer is approved. Otherwise the transfer is posted to the ledger synchronously and the call returns with a terminal successful status.

Each client_reference must be unique per entity; reusing one that already exists for the entity fails with a 400 error rather than creating a duplicate.

When called with a JWT session, this endpoint also requires a valid, unused money_action_confirmation_id (minted via POST /money-action-confirmations with action_type account_transfer after the caller re-confirms their PIN) in the request body. This requirement is skipped entirely for secret-API-key requests, since PIN confirmation only applies to interactive human sessions.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

application/json

The account transfer was created. status is successful when the transfer posted immediately, or pending-approval when it was queued for maker-checker approval instead.

Bodyapplication/json

curl --location '/account-transfers' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "source_account_id": "01HXYZ1234567890ABCDEFGHIJ", "destination_account_id": "01HXYZ9876543210ZYXWVUTSRQ", "amount": 50000, "client_reference": "transfer_88abc123" }'

{ "message": "Account transfer created successfully", "status": "success", "data": { "id": "01HXYZ5555666677778888AA", "entity_id": "01HENT1234567890ABCDEFGHIJ", "source_account_id": "01HXYZ1234567890ABCDEFGHIJ", "destination_account_id": "01HXYZ9876543210ZYXWVUTSRQ", "source_currency": "NGN", "amount": 50000, "destination_currency": "NGN", "destination_amount": 50000, "exchange_rate": 1, "applicable_fee": 0, "quote_id": null, "client_reference": "transfer_88abc123", "client_meta": null, "narration": "Move working capital to payroll account", "status": "successful", "status_reason": null, "maker_checker_approver_group_id": null, "fully_approved_at": null, "created": 1754392100000, "updated": 1754392100000 } }

Request

Responses