post https://rest.sandbox.rafiki-api.com/v1/payouts
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 events
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.The selected wallet currently doesn't have enough money to process the payout.
The account number provided is invalid.
The payment account balance has reached the maximum allowed.
The amount to be sent exceeds the maximum allowed per transaction for this payment account
The payment account has reached the daily limit or would reach it by processing this payout.
The payment account has reached the monthly limit or would reach it by processing this payout.
The payment account has reached a limit but we don't know which one.
📘
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.
Per transaction limits
| Country |
Minimum |
Maximum |
|---|
| 🇰🇪 Kenya |
KSh 140 |
| Bank Account |
Mobile Money |
|---|
| KSh 950,000 |
KSh 250,000 |
|
| 🇹🇿 Tanzania |
TSh 2,500 |
| Bank Account |
Mobile Money |
|---|
| TSh 20,000,000 |
TSh 5,000,000 |
|
| 🇷🇼 Rwanda |
R₣ 500 |
| Mobile Money |
|---|
MTN R₣ 2,000,000
Airtel R₣ 500,000
|
|
| 🇳🇬 Nigeria |
₦ 100 |
| Bank Account |
|---|
| ₦ 50,000,000 |
|
| 🇬🇭 Ghana |
₵ 10 |
| Bank Account |
Mobile Money |
|---|
| ₵ 50,000 |
₵ 15,000 |
|
| 🇺🇬 Uganda |
USh 5,000 |
| Bank Account |
Mobile Money |
|---|
| USh 5,000,000 |
USh 5,000,000 |
|
| 🇪🇬 Egypt |
£ 200 |
|
| 🇸🇳 Senegal |
XOF 2,000 |
| Mobile Money |
|---|
| XOF 1,500,000 |
|
| 🇨🇮 Côte d'Ivoire |
XOF 2,000 |
| Mobile Money |
|---|
| XOF 1,500,000 |
|
| 🇨🇲 Cameroon |
XAF 500 |
| Mobile Money |
|---|
| XAF 1,000,000 |
|
⚠️
Sender requirements
Some countries might necessitate different and more comprehensive sender details.
We understand that navigating these varying rules for different countries can be complex, considering the multitude of combinations possible. To simplify this process, you can detail the requirements for each country listed below.
🇰🇪 Kenya
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
- |
| sender.individual.identity_document.country |
- |
| sender.individual.identity_document.number |
- |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
- |
🇳🇬 Nigeria
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇹🇿 Tanzania
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇷🇼 Rwanda
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇬🇭 Ghana
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇺🇬 Uganda
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇪🇬 Egypt
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇸🇳 Senegal
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇨🇮 Côte d'Ivoire
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
🇨🇲 Cameroon
| Field |
Requirements |
| sender.type |
Required |
| sender.name |
Required |
| sender.address.line1 |
Required |
| sender.address.line2 |
- |
| sender.address.line3 |
- |
| sender.address.city |
Required |
| sender.address.postal_code |
Required |
| sender.address.country |
Required |
| sender.individual.dob |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.type |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.country |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.number |
Required (with type INDIVIDUAL) |
| sender.individual.identity_document.issued_on |
- |
| sender.individual.identity_document.expires_on |
Required (with type INDIVIDUAL) |
📱
Create account and send money
Open Recipe
Send money with existing account
Open Recipe
