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
idstringfacultatifUnique identifier (internal UUID).
referencestring?facultatifYour internal reference passed at creation.
provider_referencestring?facultatifOperator-assigned reference.
statusenumfacultatifpending, processing, succeeded, failed, cancelled.completebooleanfacultatiftrue when the transfer has reached a terminal state.amountnumberfacultatifAmount in the major unit of the currency.
currencystringfacultatifISO 4217 code.
descriptionstring?facultatifDescriptive label.
reasonstring?facultatifFailure/reversal reason code.
sourcestringfacultatifOrigin:
api, csv, dashboard.ledger_balance_beforenumber?facultatifBalance before this transfer (internal accounting).
ledger_balance_afternumber?facultatifBalance after this transfer.
timelinearray?facultatifChronological list of status events (present when loaded with events).
metadataobjectfacultatifFree-form key-value data.
succeeded_atdatetime?facultatifISO 8601 timestamp of completion.
created_atdatetimefacultatifISO 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 |