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.
private key required
Transfers require the private 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
idstringoptionalUnique identifier (internal UUID).
referencestring?optionalYour internal reference passed at creation.
provider_referencestring?optionalOperator-assigned reference.
statusenumoptional`pending`, `processing`, `succeeded`, `failed`, `cancelled`.
completebooleanoptional`true` when the transfer has reached a terminal state.
amountnumberoptionalAmount in the major unit of the currency.
currencystringoptionalISO 4217 code.
descriptionstring?optionalDescriptive label.
reasonstring?optionalFailure/reversal reason code.
sourcestringoptionalOrigin: `api`, `csv`, `dashboard`.
ledger_balance_beforenumber?optionalBalance before this transfer (internal accounting).
ledger_balance_afternumber?optionalBalance after this transfer.
timelinearray?optionalChronological list of status events (present when loaded with events).
metadataobjectoptionalFree-form key-value data.
succeeded_atdatetime?optionalISO 8601 timestamp of completion.
created_atdatetimeoptionalISO 8601 creation timestamp (UTC).
Lifecycle
Events
| Event | Trigger |
|---|---|
transfer.created | Transfer created |
transfer.processing | Transfer submitted to the operator |
transfer.succeeded | Transfer successfully executed |
transfer.failed | Transfer failed |