# Rafiki API Documentation > Documentation for Rafiki API ## Guides - [API keys](https://docs.rafiki.com/docs/api-keys.md) - [Webhooks](https://docs.rafiki.com/docs/webhooks-management.md) - [Overview](https://docs.rafiki.com/docs/country-coverage-overview.md) - [Cameroon payout](https://docs.rafiki.com/docs/country-coverage-africa-cameroon-payout.md) - [Cameroon lookup](https://docs.rafiki.com/docs/country-coverage-africa-cameroon-lookup.md) - [Congo-Brazzaville payout](https://docs.rafiki.com/docs/country-coverage-africa-congo-brazzaville-payout.md) - [Cรดte d'Ivoire payout](https://docs.rafiki.com/docs/country-coverage-africa-ivory-coast-payout.md) - [Egypt payout](https://docs.rafiki.com/docs/country-coverage-africa-egypt-payout.md) - [Ethiopia payout](https://docs.rafiki.com/docs/country-coverage-africa-ethiopia-payout.md) - [Ethiopia lookup (Beta)](https://docs.rafiki.com/docs/country-coverage-africa-ethiopia-lookup.md) - [Gabon payout](https://docs.rafiki.com/docs/country-coverage-africa-gabon-payout.md) - [Ghana payout](https://docs.rafiki.com/docs/country-coverage-africa-ghana-payout.md) - [Ghana lookup](https://docs.rafiki.com/docs/country-coverage-africa-ghana-lookup.md) - [Kenya payout](https://docs.rafiki.com/docs/country-coverage-africa-kenya-payout.md) - [Kenya lookup](https://docs.rafiki.com/docs/country-coverage-africa-kenya-lookup.md) - [Morocco payout](https://docs.rafiki.com/docs/country-coverage-africa-morocco-payout.md) - [Nigeria payout](https://docs.rafiki.com/docs/country-coverage-africa-nigeria-payout.md) - [Nigeria lookup](https://docs.rafiki.com/docs/country-coverage-africa-nigeria-lookup.md) - [Rwanda payout](https://docs.rafiki.com/docs/country-coverage-africa-rwanda-payout.md) - [Senegal payout](https://docs.rafiki.com/docs/country-coverage-africa-senegal-payout.md) - [Tanzania payout](https://docs.rafiki.com/docs/country-coverage-africa-tanzania-payout.md) - [Tanzania lookup](https://docs.rafiki.com/docs/country-coverage-africa-tanzania-lookup.md) - [Uganda payout](https://docs.rafiki.com/docs/country-coverage-africa-uganda-payout.md) - [Uganda lookup](https://docs.rafiki.com/docs/country-coverage-africa-uganda-lookup.md) - [Bangladesh payout](https://docs.rafiki.com/docs/country-coverage-asia-bangladesh-payout.md) - [India payout](https://docs.rafiki.com/docs/country-coverage-asia-india-payout.md) - [Pakistan payout](https://docs.rafiki.com/docs/country-coverage-asia-pakistan-payout.md) - [Philippines payout](https://docs.rafiki.com/docs/country-coverage-asia-philippines-payout.md) - [Mexico payout](https://docs.rafiki.com/docs/country-coverage-north-america-mexico-payout.md) - [Test Data](https://docs.rafiki.com/docs/testdata.md) - [Configure](https://docs.rafiki.com/docs/mcp-server-configure.md) ## API Reference - [๐Ÿ‘‹ Welcome](https://docs.rafiki.com/reference/welcome.md) - [๐Ÿš€ Transport](https://docs.rafiki.com/reference/transport.md) - [๐Ÿ” Authentication](https://docs.rafiki.com/reference/authentication.md) - [๐Ÿ›ก๏ธ Idempotency](https://docs.rafiki.com/reference/idempotency.md) - [๐Ÿ”ก Fields format](https://docs.rafiki.com/reference/fields-format.md) - [๐Ÿ’ฅ Error codes](https://docs.rafiki.com/reference/error-codes.md) - [๐Ÿ“š Pagination](https://docs.rafiki.com/reference/pagination.md) - [๐Ÿ“ฅ Webhooks](https://docs.rafiki.com/reference/webhooks.md) - [List](https://docs.rafiki.com/reference/get_banks.md): Within the scope of this API, the "Bank" resource serves the purpose of identifying the financial institutions that own payment accounts. This endpoint enables you to retrieve the list of banks provided by our API. - [Get](https://docs.rafiki.com/reference/get_lookups-accountnumber.md): The lookup resource facilitates the retrieval of metadata associated with mobile money or bank accounts. For instance, prior to creating payment accounts, you can utilize this endpoint to validate whether an account number corresponds to a specific business or individual. This functionality proves especially valuable in ensuring that only validated payment accounts are utilized; for example, when integrated with other processes, such as payouts, it helps mitigate the risk of costly reversals or refunds resulting from funds being sent to an incorrect recipient. ### Account not found While we strive to ensure that our lookup sources are always up to date with the most recent data, we must consider instances when we cannot retrieve metadata for a requested payment account. In such cases, our API will respond with the error code [LOOKUP_ACCOUNT_NOT_FOUND](error-codes#lookup_account_not_found-http-404), providing a way to programmatically determine whether the account lookup was unsuccessful. Lookups reliability varies a lot between countries. If you receive a 500 error, please wait a few minutes and try your request again. ### Supported countries/account types To view the complete list of supported countries and payment accounts, visit the [Country support](country-coverage-overview) section in the General tab. Each country page indicates whether lookup functionality is available for that specific country. - [List](https://docs.rafiki.com/reference/get_payment-accounts.md): Using this endpoint, you can list all your payment accounts ordered by their creation date in descending order. Considering that the returned data may contain thousands of records, the results will be paginated with a cursor [(see pagination docs)](pagination), allowing you to scroll through the data using multiple requests as necessary. - [Get or create](https://docs.rafiki.com/reference/post_payment-accounts.md): A payment account is a uniquely identifiable entity that serves the purpose of a recipient to send money to (e.g. a remittance recipient). This endpoint allows you to create payment accounts of **`MOBILE_MONEY`**, **`BANK_ACCOUNT`**, **`BANK_ACCOUNT_ROUTE`**, and **`ALIAS`** types, which can subsequently serve as recipient accounts for making [payouts](post_payouts). > ๐Ÿ’ > > Although HTTP POST is not inherently idempotent, with this endpoint, you can confidently retry the same request without inadvertently creating duplicate records. Our process involves checking the existence of the payment account first. If it exists, we promptly respond with a `200 OK` status. Otherwise, we proceed to create a new one and respond with a `201 Created` status. In both scenarios, the structure of the response body will remain identical. ### Mobile Money The **`MOBILE_MONEY`** type refers to accounts registered with telecom companies (a.k.a operators) like SAFARICOM in Kenya, and it necessitates a valid mobile number for identification of the payment account within that telecom provider. The following table outlines the operators supported by our API for each specific country: | Country | Operators | | --------- |----------------------------------------------------------------------| | ๐Ÿ‡ฐ๐Ÿ‡ช KE | SAFARICOM, AIRTEL | | ๐Ÿ‡น๐Ÿ‡ฟ TZ | VODACOM, AIRTEL, TIGO, HALOTEL, TTCL | | ๐Ÿ‡ท๐Ÿ‡ผ RW | AIRTEL, MTN | | ๐Ÿ‡ฌ๐Ÿ‡ญ GH | AT, MTN, VODAFONE | | ๐Ÿ‡บ๐Ÿ‡ฌ UG | AIRTEL, MTN | | ๐Ÿ‡จ๐Ÿ‡ฎ CI | MTN, ORANGE, MOOV | | ๐Ÿ‡ธ๐Ÿ‡ณ SN | ORANGE, FREE, EXPRESSO, WAVE | | ๐Ÿ‡จ๐Ÿ‡ฒ CM | MTN, ORANGE | | ๐Ÿ‡ง๐Ÿ‡ฉ BD | BKASH, NAGAD | | ๐Ÿ‡ต๐Ÿ‡ญ PH | GCASH, MAYA, COINS, GRABPAY | | ๐Ÿ‡ต๐Ÿ‡ฐ PK | EASYPAISA, JAZZCASH, UPAISA, SADAPAY, NAYAPAY, FINJA, PAYMAX | | ๐Ÿ‡จ๐Ÿ‡ฌ CG | MTN, AIRTEL | | ๐Ÿ‡ฌ๐Ÿ‡ฆ GA | AIRTEL, MOOV | ### Bank Account The **`BANK_ACCOUNT`** type is designated for conventional accounts registered with bank institutions, such as "Equity Bank." It comprises an account number and the associated bank ID, where accounts are registered. We provide support for numerous banks in each country. Documenting each of them here would be impractical. Therefore, we recommend utilizing the dedicated [/v1/banks](get_banks) endpoint to access the most current and accurate list of banks. ### Bank Account Route The **`BANK_ACCOUNT_ROUTE`** type is used for accounts that require both a routing code and an account number to identify the recipient bank account. This payment account type is common in payment systems that rely on routing details, such as sort codes, IFSC, etc., to direct funds accurately to the destination bank or branch. The following table outlines the routing code supported by our API for each specific country: | Country | Routing Code | | ---------- | ---------------------------------------- | | ๐Ÿ‡ฎ๐Ÿ‡ณ IN | IFSC (Indian Financial System Code) | | ๐Ÿ‡ง๐Ÿ‡ฉ BD | Bank Routing Number | ### Alias The **`ALIAS`** type represents accounts identified by a virtual or alternative payment handle rather than traditional bank account details or a mobile number. It is commonly used in payment systems where recipients can receive funds using simple identifiers such as an email address, phone number, or payment handle (e.g. UPI Virtual Payment Address). The following table outlines the alias networks supported by our API for each specific country: | Country | Network | Identifier | | ---------- | -------- | --------------------------------- | | ๐Ÿ‡ฎ๐Ÿ‡ณ IN | UPI | Virtual Payment Address (VPA) | - [List](https://docs.rafiki.com/reference/get_payouts.md): Using this endpoint, you can list all your historical payouts with an optional dates filter. Considering that the returned data may contain thousands of records, the results will be paginated with a cursor [(see pagination docs)](pagination), allowing you to scroll through the data using multiple requests as necessary. - [Create](https://docs.rafiki.com/reference/post_payouts.md): 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](get_wallets) to designated recipients (a.k.a [payment accounts](post_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](get_payouts-id) and determine whether it has succeeded or not. After the payout is completed, provided [webhook notifications](webhooks) are set up, Rafiki will also dispatch [payout.state-updated](event-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.
PAYMENT_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](country-coverage-overview) 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](country-coverage-overview) tab. - [Get](https://docs.rafiki.com/reference/get_payouts-id.md): This endpoint enables the retrieval of a previously accepted payout using its unique ID (`pyt-xxx`) or the `custom_id` submitted when creating it. Its primary purpose is to periodically check for changes in the payout status. To learn more about the lifecycle of payouts, please refer to the dedicated section under the [Send Money](post_payouts) endpoint. - [Create](https://docs.rafiki.com/reference/post_wallet-statements.md): The wallet statement resource allows you to generate detailed transaction statements for your wallets over a specified time period. Statements provide a comprehensive view of all wallet activity, including payouts, collections, and currency conversions, along with opening and closing balances. ## โ„น๏ธ Lifecycle When you submit a request to create a statement, our server validates the request and accepts it for processing. The statement generation is handled asynchronously, and an HTTP 202 status code is returned along with the statement unique identifier. Upon acceptance, the statement is marked as **PENDING**. Your client program will need to poll at intervals to [query the statement state](get_wallet-statements-id) and determine whether it has completed processing. After the statement is completed, provided webhook notifications are set up, Rafiki will also dispatch [wallet-statement.state-updated](event-wallet-statement-state-updated) event.
Statement States
State Description
โณ
PENDING		 Your statement request has been accepted, and it is currently being generated.
โœ…
READY		 The statement has been successfully generated and is ready to be retrieved. You can now list the statement lines.
๐Ÿ’”
FAILED		 The statement generation failed. Please contact support if this persists.
## ๐Ÿ“… Period Requirements The `from` and `to` fields in the period must be valid dates or RFC3339 datetime strings with **hour precision**. This means: - Dates like `2025-01-01` are valid (interpreted as `2025-01-01T00:00:00Z`) - Datetimes like `2025-01-01T00:00:00Z` or `2025-01-31T23:00:00Z` are valid - Datetimes with minutes or seconds other than `00` (e.g., `2025-01-01T00:30:00Z`) are **not valid** The `from` date must be before the `to` date. - [Get](https://docs.rafiki.com/reference/get_wallet-statements-id.md): Retrieve the details of a specific wallet statement by its unique identifier. This endpoint returns the statement metadata including its current state, the time period it covers, and the starting and closing balances for that period. Once the statement state is `READY`, you can use the [List Lines](get_wallet-statements-id-lines) endpoint to retrieve the individual transaction lines. - [List Lines](https://docs.rafiki.com/reference/get_wallet-statements-id-lines.md): Retrieve the individual lines for a wallet statement. Each line represents a single transaction that affected the wallet balance during the statement period, including the line type, amount, and running balance after the line. ## โš ๏ธ Statement Must Be Ready This endpoint can only be called when the statement state is `READY`. If the statement is still being processed (`PENDING`) or has failed (`FAILED`), an HTTP 409 Conflict error will be returned. You can check the statement state using the [Get Statement](get_wallet-statements-id) endpoint before calling this endpoint. ## ๐Ÿ“‹ Line Types Each statement line includes a `type` field indicating the nature of the transaction: | Type | Description | |------|-------------| | `COLLECTION_COLLECTED` | Funds collected into the wallet | | `COLLECTION_CONVERTED` | Collected funds converted to wallet currency | | `CONVERSION_INITIATED` | Currency conversion initiated | | `CONVERSION_CONVERTED` | Currency conversion completed | | `PAYOUT_INITIATED` | Payout initiated from wallet (debit) | | `PAYOUT_FAILED` | Payout failed, funds returned to wallet (credit) | | `PAYOUT_REVERSED` | Payout reversed, funds returned to wallet (credit) | | `PAYOUT_SENT_TO_FAILED` | Previously sent payout moved to failed state | | `PAYOUT_FAILED_TO_SENT` | Previously failed payout moved to sent state | ## ๐Ÿ”— Resource References Where applicable, each line includes a `resource` object with references to the associated transaction (e.g., payout ID, collection ID). This allows you to cross-reference statement lines with other API resources. ## ๐Ÿ“„ Pagination Results are paginated. Use the `paging_limit` parameter to control how many lines are returned per request (default and maximum vary by configuration). Use the `paging_after` cursor from the response metadata to fetch subsequent pages. - [List](https://docs.rafiki.com/reference/get_wallets.md): Wallets serve as repositories for your funds in a specific currency and are employed in tandem with payouts as the origin from which funds will be disbursed. This particular endpoint will return a comprehensive list of your active wallets, showcasing their associated currencies and the most recent updates on available balances. - [State updated](https://docs.rafiki.com/reference/event-payout-state-updated.md) - [State updated](https://docs.rafiki.com/reference/event-wallet-statement-state-updated.md) ## Recipes - [Create account and send money](https://docs.rafiki.com/recipes/create-account-and-send-money.md) - [Create bank account](https://docs.rafiki.com/recipes/create-bank-account.md) - [Create mobile money account](https://docs.rafiki.com/recipes/create-mobile-money-account.md) - [Lookup bank account](https://docs.rafiki.com/recipes/lookup-bank-account.md) - [Lookup mobile money](https://docs.rafiki.com/recipes/lookup-mobile-money.md) - [Send money with existing account](https://docs.rafiki.com/recipes/send-money-with-existing-account.md)