Transfer API
Transaction callbacks
SolFi sends notifications (callbacks) to your server to inform you of transaction statuses. You must expose a POST route to receive these notifications.
Callback behaviour
SolFi sends exactly one notification for a transaction, when it reaches its final status (SUCCESS or FAILED). There is no follow-up and no correction callback: once either status is reached, no further notification will be sent for that transaction.
That single notification may be delivered more than once — but it is always the same notification. If your endpoint does not return a 2xx, or is unreachable, we retry: up to 4 attempts in total, with exponential backoff, the first retry occurring about 30 seconds later.
Every attempt sends an identical payload — same event, same data.status, same data.timestamp. A retry never signals a change; it only means we had not yet received your 2xx. data.timestamp reflects when the transaction reached its final status, not when a given attempt was sent.
Make your handler idempotent
If your 2xx is lost in transit, we will retry a callback you have already processed. Deduplicate on data.id.
If no callback arrives
Do not assume the transfer failed. A callback can be missed for reasons unrelated to the transaction outcome. Query the transaction instead: GET /transactions/{id or externalId}.
Available events
transfer.success— the transaction was successfully completed.transfer.failed— the transaction failed.
Request format
| Property | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| URL | Your callback endpoint (provided in callbackUrl when creating the transaction) |
Received payload
{
"event": "transfer.success",
"data": {
"id": "cf1480c5-aa21-4205-a5f2-d67d7e56bf05",
"externalId": "uuid-string",
"reference": "tr-4kslbazu27y5hqnbn5",
"status": "SUCCESS",
"amount": 10000,
"currency": "XAF",
"paymentMethod": "mobile_money",
"walletNumber": "+237690000000",
"bankAccount": null,
"provider": "Orange_CM",
"vouchercode": "e9vSKR0AvNl3",
"failureReason": null,
"timestamp": "2026-02-17T13:55:57.285Z",
"externalReference": "1771336516459"
}
}Data structure
| Field | Type | Description |
|---|---|---|
| event | string | Event type: transfer.success or transfer.failed |
| data.id | string | Unique transaction identifier |
| data.externalId | string | Unique identifier generated by the merchant |
| data.reference | string | Transaction reference |
| data.status | string | Transaction status: SUCCESS or FAILED |
| data.amount | number | Transaction amount |
| data.currency | string | Currency (e.g. XAF, USD, EUR) |
| data.paymentMethod | string | mobile_money or bank |
| data.walletNumber | string | Beneficiary's mobile money number (null for bank payments) |
| data.bankAccount | object | Bank account details (null for mobile money payments) |
| data.provider | string | Operator or bank used for the payout |
| data.failureReason | string | Reason for failure (null when successful) |
| data.timestamp | string | Moment the transaction reached its final status |
| data.externalReference | string | Provider-side reference for the operation |