API Reference

Create

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 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
The context property of the payout state provides additional information about the payout status. Contexts can be returned for both PENDING and FAILED payouts, depending on the specific circumstances.

Contexts for PENDING Payouts:
Context Code Description
COMPLIANCE_REVIEW The payout is undergoing compliance review and requires additional verification before it can be processed.

Contexts for FAILED Payouts:
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.
RECIPIENT_ACCOUNT_NOT_SUPPORTED_FOR_REMITTANCE The transaction was rejected due to the recipient account not being eligible for international remittances.

📘 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.

Body Params

The payout

amount
object

required

The intended amount to send to either the payment_account_id or payment_account

string

An optional unique custom id that can be used to reconcile payouts with your own internal systems, this is particularly useful in the event of network failures.

The accepted format can include up to 64 characters, which may consist of both letters, digits, and the symbols "-" and "_".

on_behalf_of
array of strings

This field is required for integrators processing payments on behalf of another party. You must input the Legal Entity Name of the organization on behalf of whom you are processing payments.

on_behalf_of
payment_account
object

required if payment_account_id is empty

You have the option to create a payment account on the spot by including it here. If it doesn't already exist, it will be created and automatically employed as the recipient for the payout request. If it already exists, we will simply retrieve it and utilize it, preventing the creation of duplicate accounts.

string

required if payment_account is empty

The payment account ID represents a pre-existing payment account that acts as the recipient for the payout.

string
enum

required if payment_account country is GH,UG,EG,CI,SN or CM

The purpose of the payout is a mandatory property that must be provided for compliance and reporting purposes. Choose one of the following predefined values that best describes the nature of the payout:

  • GOODS_PURCHASE: Payments made for buying physical or digital goods.
  • SERVICES_PAYMENT: Payments made for services rendered, including professional services, consulting, and freelance work.
  • INVOICE_PAYMENT: Payments made to settle invoices issued for goods or services.
  • LOAN_REPAYMENT: Payments made towards repaying loans, including personal, auto, mortgage, and business loans.
  • BILLS_PAYMENT: Payments for recurring bills such as utilities, rent, insurance, and telecommunications.
  • SALARY_AND_WAGES: Disbursements made to employees for their salaries and wages.
  • P2P_TRANSFER: Domestic person-to-person transfers for sending money to friends, family, or acquaintances.
  • REMITTANCE: Cross-border person-to-person transfers for sending money to friends, family, or acquaintances.
  • DONATION: Payments made to charitable organizations or causes.
  • GRANTS_AND_SCHOLARSHIPS: Payments distributed as grants, scholarships, or other forms of financial aid.
  • TRAVEL_AND_ACCOMMODATION: Payments made for travel-related expenses, including flight bookings, hotel reservations, and car rentals.
  • TAX_PAYMENT: Payments made for settling taxes and duties.
  • INSURANCE_PREMIUM: Payments made towards insurance policies, including health, auto, and life insurance.
sender
object

An optional property for incorporating sender details. Please refer to the "💡 Compliance requirements" documentation above.

string

The wallet ID from which to disburse money, if not provided, we will attempt to use the one that matches the provided currency amount.

Headers
string
required

🚨️ Prevent duplicate payouts! See: x-idempotency-key security scheme

Responses

Updated 3 months ago

Language
Credentials
Header
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 3 months ago