The payout resource finds its application in various scenarios where funds need to be disbursed electronically; For example, but not limited to, money remittance services or businesses that need to disburse salaries to their employees.
Regardless of your specific use case, this endpoint has you covered, offering a versatile API to facilitate money disbursement from your local wallets to designated recipients (a.k.a payment accounts).
ℹ️ Lifecycle
If the request you submit meets our minimum validation standards for processing the payout, our server will accept the request. It will defer the execution to a background asynchronous process, and in response, send you an HTTP 202 status code, along with the payout unique identifier.
Upon acceptance, the payout is marked as pending. Your client program will need to poll at intervals to query the payout state and determine whether it has succeeded or not. After the payout is completed, provided webhook notifications are set up, Rafiki will also dispatch payout.state-updated event
Payout States
| State | Description |
|---|---|
| ⏳ PENDING |
Your payout has been accepted, and it is currently awaiting processing. |
| 🎉 SENT |
The payout has been successfully processed, and the intended recipient should have received the funds. |
| 🔙 REVERSED |
Upon reaching the "SENT" state, you can request a manual reversal (for instance, if funds were sent to the wrong recipient) by contacting our support team. Please be aware that there is no programmatic API available for this process yet. This state indicates a successful reversal. |
| 🙅 CANCELLED |
If the payout has not yet reached the intended recipient, you have the option to request manual cancellation by reaching out to our support team (please note that there is no programmatic API for this yet). This state signifies that the payout has been successfully canceled. |
| 💔 FAILED |
The funds did not reach the intended recipient due to a failure. If the "context" property does not provide specific information about the reason for the failure, please contact our customer support for assistance. |
Payout State Context
When a payout fails, the "context" property of the state object will provide additional information about the reason for the failure. The table below outlines the possible values for this property.
| Context Code | Description |
|---|---|
WALLET_INSUFFICIENT_BALANCE |
The selected wallet currently doesn't have enough money to process the payout. |
PAYMENT_ACCOUNT_INVALID_ACCOUNT_NUMBER |
The account number provided is invalid. |
PAYMENT_ACCOUNT_BALANCE_MAXED_OUT |
The payment account balance has reached the maximum allowed. |
PAYMENT_ACCOUNT_PER_TRANSACTION_LIMIT_REACHED |
The amount to be sent exceeds the maximum allowed per transaction for this payment account. |
PAYMENT_ACCOUNT_DAILY_LIMIT_REACHED |
The payment account has reached the daily limit or would reach it by processing this payout. |
PAYMENT_ACCOUNT_WEEKLY_LIMIT_REACHED |
The payment account has reached its weekly transaction limit, or this payout would exceed the allowed limit for the current week. |
PAYMENT_ACCOUNT_MONTHLY_LIMIT_REACHED |
The payment account has reached the monthly limit or would reach it by processing this payout. |
PAYMENT_ACCOUNT_LIMIT_REACHED |
The payment account has reached a limit, but we don't know which one. |
ENTITY_PAYMENT_ACCOUNT_KYC_SANCTIONS_HIT |
The payment account had a sanction list hit during transaction screening. |
ENTITY_SENDER_KYC_SANCTIONS_HIT |
The sender had a sanction list hit during transaction screening. |
ENTITY_KYC_SANCTIONS_HIT_EXPIRED |
The sanction list hit has not been cleared within a defined threshold. |
PROVIDER_NETWORK_ISSUE |
The transaction could not be completed due to a temporary issue with the provider's network or systems. |
📘 Payout amount limits
Depending on the payment account type and destination currency, different transactions amount limits apply.
Such limits might be enforced for compliance reasons or mandated by the banking authority that owns the payment account or the country in which the account resides.
The payout amount limits for each country are detailed on each of the respective country pages in the General tab.
⚠️ Compliance requirements
Some countries might necessitate different and more comprehensive fields to comply with the local regulations.
We understand that navigating these varying rules for different countries can be complex, considering the multitude of combinations possible. To simplify this process, we have detailed the requirements on each of the respective country pages in the General tab.