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 |
Bank Account |
Mobile Money |
KSh 100 |
KSh 10 |
|
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 |
Bank Account |
Mobile Money |
Rโฃ 1,000 |
Rโฃ 300
|
|
Bank Account |
Mobile Money |
Rโฃ 8,000,000 |
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 |
(WAVE) XOF 2,000,000 |
(ORANGE, FREE, EXPRESSO) 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