Transfers

Send funds to a Mobile Money wallet or bank account via the Transfers API.

A Transfer is an outgoing payout from the balance held by our licensed payment partner. Transfers are asynchronous — listen to transfer.succeeded and transfer.failed.

Secret key required

Transfers require the secret key (sk...) in the Authorization header.

Marketplaces: acting on behalf of a subaccount

Platforms can pay out on behalf of a connected subaccount by sending an X-Sync header alongside their own key (requires the withdrawals capability) — see Subaccounts for the full contract and error cases.

Endpoints

Method	Path	Description
`POST`	`/transfers`	Create a transfer
`GET`	`/transfers`	List transfers
`GET`	`/transfers/{id}`	Retrieve a transfer

The Transfer object

idstringoptional

Unique identifier (internal UUID).

referencestring?optional

Your internal reference passed at creation.

provider_referencestring?optional

Operator-assigned reference.

statusenumoptional

`pending`, `processing`, `succeeded`, `failed`, `cancelled`.

completebooleanoptional

`true` when the transfer has reached a terminal state.

amountnumberoptional

Amount in the major unit of the currency.

currencystringoptional

ISO 4217 code.

descriptionstring?optional

Descriptive label.

reasonstring?optional

Failure/reversal reason code.

sourcestringoptional

Origin: `api`, `csv`, `dashboard`.

ledger_balance_beforenumber?optional

Balance before this transfer (internal accounting).

ledger_balance_afternumber?optional

Balance after this transfer.

timelinearray?optional

Chronological list of status events (present when loaded with events).

metadataobjectoptional

Free-form key-value data.

succeeded_atdatetime?optional

ISO 8601 timestamp of completion.

created_atdatetimeoptional

ISO 8601 creation timestamp (UTC).

Lifecycle

Transfer lifecycle

pendingprocessingsubmitted to operatorsucceededwebhook transfer.succeeded

Terminal statesfailedwebhook transfer.failedcancelledcancelled before dispatch

Events

Event	Trigger
`transfer.created`	Transfer created
`transfer.processing`	Transfer submitted to the operator
`transfer.succeeded`	Transfer successfully executed
`transfer.failed`	Transfer failed

BalanceCheck available balance before a transfer.Failure ReasonsTransfer failure reason catalog.WebhooksReceive transfer events in real time.