{"openapi":"3.0.0","info":{"title":"Resources","contact":{},"version":"1"},"paths":{"/banks":{"get":{"security":[{"Bearer":[]}],"description":"Within the scope of this API, the \"Bank\" resource serves the purpose of identifying the financial institutions that own payment accounts.\n\nThis endpoint enables you to retrieve the list of banks provided by our API.\n","tags":["Bank"],"summary":"List","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessCollectionNoMeta"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"description":"The ISO 3166 alpha-2 country code in which the bank operates.","type":"string","example":"TZ"},"id":{"type":"string","format":"ksuid","example":"bnk-xxx"},"name":{"type":"string","example":"TIB Corporate Bank Limited"}}}}}}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/lookups/{accountNumber}":{"get":{"security":[{"Bearer":[]}],"description":"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.\n\nThis 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.\n\n### Account not found\n\nWhile 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.\n\nIn 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.\n\nLookups reliability varies a lot between countries. If you receive a 500 error, please wait a few minutes and try your request again.\n\n### Supported countries/account types\n\nTo view the complete list of supported countries and payment accounts, visit the [Country support](country-coverage-overview) section in the General tab.\n\nEach country page indicates whether lookup functionality is available for that specific country.","tags":["Lookup"],"summary":"Get","parameters":[{"description":"The payment account type to lookup for","name":"payment_account_type","in":"query","required":true,"schema":{"type":"string","enum":["MOBILE_MONEY","BANK_ACCOUNT"]}},{"description":"If payment_account_type is BANK_ACCOUNT, this will be a mandatory field representing the bank id (bnk-xxx) used to identify which bank the account number belongs to","name":"bank_id","in":"query","schema":{"type":"string"}},{"description":"The account number, that is either the mobile money number or bank account number","name":"accountNumber","in":"path","required":true,"schema":{"type":"string"}},{"description":"If payment_account_type is MOBILE_MONEY, this will be a mandatory field representing the mobile money operator","name":"operator","in":"query","schema":{"type":"string","enum":["SAFARICOM","AT","AIRTEL","VODACOM","TIGO","HALOTEL","TTCL","MTN","VODAFONE","MOOV","ORANGE","FREE","EXPRESSO","WAVE","GCASH","MAYA","COINS","GRABPAY","EASYPAISA","JAZZCASH","UPAISA","SADAPAY","NAYAPAY","FINJA","PAYMAX"]}}],"responses":{"200":{"description":"The found looked up account number information","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.LookupGetResponse"}}}]}}}},"404":{"description":"The provided account identifier is unregistered / couldn't be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyLookupAccountNotFound"}}}},"422":{"description":"Validation failed, e.g. missing payment_account_type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/payins":{"post":{"security":[{"Bearer":[]}],"description":"> 🏗️ **Alpha Feature:** This feature is currently in alpha and is not yet rolled out to the public. If you are a customer, please note this isn't available yet.\n\nThe payin resource is used when you need to receive funds electronically from a customer. It allows you to collect payments from [payment accounts](post_payment-accounts) and deposit them into your [local wallets](get_wallets).\n\nRegardless of your specific use case, this endpoint has you covered, offering a versatile API to facilitate money collection.\n\n## ℹ️ Lifecycle\n\nIf the request you submit meets our minimum validation standards for processing the payin, 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 payin unique identifier.\n\nUpon acceptance, the payin is marked as pending. Your client program will need to poll at intervals to [query the payin state](get_payins-id) and determine whether it has succeeded or not. After the payin is completed, provided [webhook notifications](webhooks) are set up, Rafiki will also dispatch [payin.state-updated](event-payin-state-updated) event.\n<details>\n <summary>Payin States</summary>\n<br>\n <table>\n   <thead>\n        <tr>\n            <th>State</th>\n            <th>Description</th>\n        </tr>\n    </thead>\n    <tbody>\n        <tr>\n            <th>⏳<br>PENDING</th>\n            <th>Your payin has been accepted, and it is currently awaiting processing.</th>\n        </tr>\n        <tr>\n           <th>🎉<br>COLLECTED</th>\n           <th>The funds have been collected from the source account and are currently being processed for settlement.</th>\n        </tr>\n        <tr>\n           <th>✅<br>SETTLED</th>\n           <th>The payin has been successfully settled, and the funds are now available in your wallet.</th>\n        </tr>\n        <tr>\n           <th>💔<br>FAILED</th>\n           <th>\n               The funds were not collected 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.\n           </th>\n        </tr>\n    </tbody>\n  </table>\n </details>\n\n<details>\n    <summary>Payin State Context</summary>\n    <br>\nThe context property of the payin state provides additional information about the payin status. Contexts can be returned for both PENDING and FAILED payins, depending on the specific circumstances.\n<br>\n<br>\n<strong>Contexts for FAILED Payins:</strong>\n<br>\n<table>\n  <thead>\n    <tr>\n      <th>Context Code</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_INSUFFICIENT_BALANCE</code></td>\n      <td>The selected source account currently doesn't have enough money to process the payin.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_HOLDER_REJECTED</code></td>\n      <td>The payment account holder has explicitly rejected the payment (e.g. STK push reject).</td>\n    </tr>\n    <tr>\n      <td><code>EXPIRED</code></td>\n      <td>The payin request has expired as it was not completed within the required timeframe. (No money collected)</td>\n    </tr>\n  </tbody>\n</table>\n</details>\n\n## 📘 Payin amount limits\nDepending on the payment account type and source currency, different transactions amount limits apply.\n\nSuch 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.\n\nThe payin amount limits for each country are detailed on each of the respective country pages in the [General](country-coverage-overview) tab.\n\n## ⚠️ Compliance requirements\n\nSome countries might necessitate different and more comprehensive fields to comply with the local regulations.\n\nWe 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.\n","tags":["Payin"],"summary":"[ALPHA] Create","parameters":[{"description":"🚨️ Prevent duplicate payins! See: [x-idempotency-key security scheme](idempotency)","name":"X-Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.PayinCreateRequest"}}},"description":"The payin","required":true},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PayinCreateResponse"}}}]}}}},"409":{"description":"Idempotency conflict, see [error codes](error-codes#idempotency_race-http-409)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyIdempotencyConflict"}}}},"422":{"description":"Validation failed, see [error codes](error-codes#validation_failed-http-422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/payins/{id}":{"get":{"security":[{"Bearer":[]}],"description":"> 🏗️ **Alpha Feature:** This feature is currently in alpha and is not yet rolled out to the public. If you are a customer, please note this isn't available yet.\n\nThis endpoint enables the retrieval of a previously accepted payin using its unique ID (`pyn-xxx`) or the `custom_id` submitted when creating it. Its primary purpose is to periodically check for changes in the payin status.\n\nTo learn more about the lifecycle of payins, please refer to the dedicated section under the [Receive Money](post_payins) endpoint.\n","tags":["Payin"],"summary":"[ALPHA] Get","parameters":[{"description":"The Payin ID (pyn-xxx) or the custom_id provided at the time of payin creation","name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PayinGetResponse"}}}]}}}},"404":{"description":"Couldn't find any payin with the provided ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyNotFound"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/payment-accounts":{"get":{"security":[{"Bearer":[]}],"description":"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.\n","tags":["Payment Account"],"summary":"List","parameters":[{"description":"The count of items returned as part of the pagination cursor iteration, minimum value is 1 and maximum 50","name":"paging_limit","in":"query","schema":{"type":"integer"}},{"description":"The base64 URL encoded cursor used to access the next set of paginated results","name":"paging_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessCollection"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateResponse"}},"meta":{"$ref":"#/components/schemas/openapi.PaymentAccountListResponseMeta"}}}]}}}},"422":{"description":"Validation failed, see [error codes](error-codes#validation_failed-http-422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}},"post":{"security":[{"Bearer":[]}],"description":"A payment account is a uniquely identifiable entity that serves the purpose of a recipient to send money to (e.g. a remittance recipient).\n\nThis 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).\n\n> 💁\n>\n> 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.\n\n### Mobile Money\n\nThe **`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.\n\nThe following table outlines the operators supported by our API for each specific country:\n\n| Country   | Operators                                                            |\n| --------- |----------------------------------------------------------------------|\n| 🇰🇪 KE     | SAFARICOM, AIRTEL                                                    |\n| 🇹🇿 TZ     | VODACOM, AIRTEL, TIGO, HALOTEL, TTCL                                 |\n| 🇷🇼 RW     | AIRTEL, MTN                                                          |\n| 🇬🇭 GH     | AT, MTN, VODAFONE                                                    |\n| 🇺🇬 UG     | AIRTEL, MTN                                                          |\n| 🇨🇮 CI     | MTN, ORANGE, MOOV                                                    |\n| 🇸🇳 SN     | ORANGE, FREE, EXPRESSO, WAVE                                         |\n| 🇨🇲 CM     | MTN, ORANGE                                                          |\n| 🇧🇩 BD     | BKASH, NAGAD                                                         |\n| 🇵🇭 PH     | GCASH, MAYA, COINS, GRABPAY                                          |\n| 🇵🇰 PK     | EASYPAISA, JAZZCASH, UPAISA, SADAPAY, NAYAPAY, FINJA, PAYMAX         |\n| 🇨🇬 CG     | MTN, AIRTEL                                                          |\n| 🇬🇦 GA     | AIRTEL, MOOV                                                         |\n\n### Bank Account\n\nThe **`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.\n\nWe 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.\n\n### Bank Account Route\n\nThe **`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.\n\n\nThe following table outlines the routing code supported by our API for each specific country:\n\n| Country    | Routing Code                             |\n| ---------- | ---------------------------------------- |\n| 🇮🇳 IN      | IFSC (Indian Financial System Code)      |\n| 🇧🇩 BD      | Bank Routing Number                      |\n\n### Alias\n\nThe **`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).\n\nThe following table outlines the alias networks supported by our API for each specific country:\n\n| Country    | Network  | Identifier                        |\n| ---------- | -------- | --------------------------------- |\n| 🇮🇳 IN      | UPI      | Virtual Payment Address (VPA)     |\n","tags":["Payment Account"],"summary":"Get or create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateRequest"}}},"description":"The payment account","required":true},"responses":{"200":{"description":"The already existing payment account was returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateResponse"}}}]}}}},"201":{"description":"The payment account was created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateResponse"}}}]}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/payouts":{"get":{"security":[{"Bearer":[]}],"description":"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.\n\n\n\n\n","tags":["Payout"],"summary":"List","parameters":[{"description":"Filters for payouts created from the specified datetime. The expected format can be either a standard date (YYYY-MM-DD) that defaults to 00:00:00 UTC or a valid RFC3339 string, including time and/or offset information.","name":"created_at_from","in":"query","schema":{"type":"string"}},{"description":"Filters for payouts created before the specified datetime. The expected format can be either a standard date (YYYY-MM-DD) that defaults to 23:59:59 UTC or a valid RFC3339 string, including time and/or offset information.","name":"created_at_to","in":"query","schema":{"type":"string"}},{"description":"The count of items returned as part of the pagination cursor iteration, minimum value is 1 and maximum 50","name":"paging_limit","in":"query","schema":{"type":"integer"}},{"description":"The base64 URL encoded cursor used to access the next set of paginated results","name":"paging_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessCollection"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/openapi.PayoutGetResponse"}},"meta":{"$ref":"#/components/schemas/openapi.PayoutListResponseMeta"}}}]}}}},"422":{"description":"Validation failed, see [error codes](error-codes#validation_failed-http-422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}},"post":{"security":[{"Bearer":[]}],"description":"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.\n\nRegardless 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)).\n\n## ℹ️ Lifecycle\n\nIf 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.\n\nUpon 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.\n<details>\n <summary>Payout States</summary>\n<br>\n <table>\n   <thead>\n        <tr>\n            <th>State</th>\n            <th>Description</th>\n        </tr>\n    </thead>\n    <tbody>\n        <tr>\n            <th>⏳<br>PENDING</th>\n            <th>Your payout has been accepted, and it is currently awaiting processing.</th>\n        </tr>\n        <tr>\n           <th>🎉<br>SENT</th>\n           <th>The payout has been successfully processed, and the intended recipient should have received the funds.</th>\n        </tr>\n        <tr>\n           <th>🔙<br>REVERSED</th>\n           <th>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.</th>\n        </tr>\n        <tr>\n           <th>🙅<br>CANCELLED</th>\n           <th>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.</th>\n        </tr>\n        <tr>\n           <th>💔<br>FAILED</th>\n           <th>\n               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.\n           </th>\n        </tr>\n    </tbody>\n  </table>\n </details>\n\n<details>\n    <summary>Payout State Context</summary>\n    <br>\nThe 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.\n<br>\n<br>\n<strong>Contexts for PENDING Payouts:</strong>\n<br>\n<table>\n  <thead>\n    <tr>\n      <th>Context Code</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td><code>COMPLIANCE_REVIEW</code></td>\n      <td>The payout is undergoing compliance review and requires additional verification before it can be processed.</td>\n    </tr>\n  </tbody>\n</table>\n<br>\n<strong>Contexts for FAILED Payouts:</strong>\n<br>\n<table>\n  <thead>\n    <tr>\n      <th>Context Code</th>\n      <th>Description</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td><code>WALLET_INSUFFICIENT_BALANCE</code></td>\n      <td>The selected wallet currently doesn't have enough money to process the payout.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_INVALID_ACCOUNT_NUMBER</code></td>\n      <td>The account number provided is invalid.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_BALANCE_MAXED_OUT</code></td>\n      <td>The payment account balance has reached the maximum allowed.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_PER_TRANSACTION_LIMIT_REACHED</code></td>\n      <td>The amount to be sent exceeds the maximum allowed per transaction for this payment account.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_DAILY_LIMIT_REACHED</code></td>\n      <td>The payment account has reached the daily limit or would reach it by processing this payout.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_WEEKLY_LIMIT_REACHED</code></td>\n      <td>The payment account has reached its weekly transaction limit, or this payout would exceed the allowed limit for the current week.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_MONTHLY_LIMIT_REACHED</code></td>\n      <td>The payment account has reached the monthly limit or would reach it by processing this payout.</td>\n    </tr>\n    <tr>\n      <td><code>PAYMENT_ACCOUNT_LIMIT_REACHED</code></td>\n      <td>The payment account has reached a limit, but we don't know which one.</td>\n    </tr>\n    <tr>\n      <td><code>ENTITY_PAYMENT_ACCOUNT_KYC_SANCTIONS_HIT</code></td>\n      <td>The payment account had a sanction list hit during transaction screening.</td>\n    </tr>\n    <tr>\n      <td><code>ENTITY_SENDER_KYC_SANCTIONS_HIT</code></td>\n      <td>The sender had a sanction list hit during transaction screening.</td>\n    </tr>\n    <tr>\n      <td><code>ENTITY_KYC_SANCTIONS_HIT_EXPIRED</code></td>\n      <td>The sanction list hit has not been cleared within a defined threshold.</td>\n    </tr>\n    <tr>\n      <td><code>PROVIDER_NETWORK_ISSUE</code></td>\n      <td>The transaction could not be completed due to a temporary issue with the provider's network or systems.</td>\n    </tr>\n    <tr>\n      <td><code>RECIPIENT_ACCOUNT_NOT_SUPPORTED_FOR_REMITTANCE</code></td>\n      <td>The transaction was rejected due to the recipient account not being eligible for international remittances.</td>\n    </tr>\n  </tbody>\n</table>\n</details>\n\n## 📘 Payout amount limits\nDepending on the payment account type and destination currency, different transactions amount limits apply.\n\nSuch 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.\n\nThe payout amount limits for each country are detailed on each of the respective country pages in the [General](country-coverage-overview) tab.\n\n## ⚠️ Compliance requirements\n\nSome countries might necessitate different and more comprehensive fields to comply with the local regulations.\n\nWe 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.\n\n","tags":["Payout"],"summary":"Create","parameters":[{"description":"🚨️ Prevent duplicate payouts! See: [x-idempotency-key security scheme](idempotency)","name":"X-Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.PayoutCreateRequest"}}},"description":"The payout","required":true},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PayoutCreateResponse"}}}]}}}},"402":{"description":"Not enough balance, see [error codes](error-codes#wallet_insufficient_balance-http-402)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyWalletInsufficientBalance"}}}},"409":{"description":"Idempotency conflict, see [error codes](error-codes#idempotency_race-http-409)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyIdempotencyConflict"}}}},"422":{"description":"Validation failed, see [error codes](error-codes#validation_failed-http-422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}},"503":{"description":"Receiving bank/operation temporarily unavailable see [error codes](error-codes)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyPayoutPaymentAccountTemporarilyUnavailable"}}}}}}},"/payouts/{id}":{"get":{"security":[{"Bearer":[]}],"description":"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.\n\nTo learn more about the lifecycle of payouts, please refer to the dedicated section under the [Send Money](post_payouts) endpoint.\n","tags":["Payout"],"summary":"Get","parameters":[{"description":"The Payout ID (pyt-xxx) or the custom_id provided at the time of payout creation","name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.PayoutGetResponse"}}}]}}}},"404":{"description":"Couldn't find any payout with the provided ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyNotFound"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/wallet-statements":{"post":{"security":[{"Bearer":[]}],"description":"The wallet statement resource allows you to generate detailed transaction statements for your wallets over a specified time period.\n\nStatements provide a comprehensive view of all wallet activity, including payouts, collections, and currency conversions, along with opening and closing balances.\n\n## ℹ️ Lifecycle\n\nWhen 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.\n\nUpon 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.\n\n<details>\n <summary>Statement States</summary>\n<br>\n <table>\n   <thead>\n        <tr>\n            <th>State</th>\n            <th>Description</th>\n        </tr>\n    </thead>\n    <tbody>\n        <tr>\n            <th>⏳<br>PENDING</th>\n            <th>Your statement request has been accepted, and it is currently being generated.</th>\n        </tr>\n        <tr>\n           <th>✅<br>READY</th>\n           <th>The statement has been successfully generated and is ready to be retrieved. You can now list the statement lines.</th>\n        </tr>\n        <tr>\n           <th>💔<br>FAILED</th>\n           <th>The statement generation failed. Please contact support if this persists.</th>\n        </tr>\n    </tbody>\n  </table>\n </details>\n\n## 📅 Period Requirements\n\nThe `from` and `to` fields in the period must be valid dates or RFC3339 datetime strings with **hour precision**. This means:\n\n- Dates like `2025-01-01` are valid (interpreted as `2025-01-01T00:00:00Z`)\n- Datetimes like `2025-01-01T00:00:00Z` or `2025-01-31T23:00:00Z` are valid\n- Datetimes with minutes or seconds other than `00` (e.g., `2025-01-01T00:30:00Z`) are **not valid**\n\nThe `from` date must be before the `to` date.\n","tags":["Wallet Statement"],"summary":"Create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.WalletStatementCreateRequest"}}},"description":"The statement request","required":true},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.WalletStatementResponse"}}}]}}}},"422":{"description":"Validation failed, see [error codes](error-codes#validation_failed-http-422)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyValidationFailed"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/wallet-statements/{id}":{"get":{"security":[{"Bearer":[]}],"description":"Retrieve the details of a specific wallet statement by its unique identifier.\n\nThis endpoint returns the statement metadata including its current state, the time period it covers, and the starting and closing balances for that period.\n\nOnce the statement state is `READY`, you can use the [List Lines](get_wallet-statements-id-lines) endpoint to retrieve the individual transaction lines.\n","tags":["Wallet Statement"],"summary":"Get","parameters":[{"description":"The Wallet Statement ID (stm-xxx)","name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessNoMeta"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/openapi.WalletStatementResponse"}}}]}}}},"404":{"description":"Couldn't find any statement with the provided ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyNotFound"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/wallet-statements/{id}/lines":{"get":{"security":[{"Bearer":[]}],"description":"Retrieve the individual lines for a wallet statement.\n\nEach 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.\n\n## ⚠️ Statement Must Be Ready\n\nThis 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.\n\nYou can check the statement state using the [Get Statement](get_wallet-statements-id) endpoint before calling this endpoint.\n\n## 📋 Line Types\n\nEach statement line includes a `type` field indicating the nature of the transaction:\n\n| Type | Description |\n|------|-------------|\n| `COLLECTION_COLLECTED` | Funds collected into the wallet |\n| `COLLECTION_CONVERTED` | Collected funds converted to wallet currency |\n| `CONVERSION_INITIATED` | Currency conversion initiated |\n| `CONVERSION_CONVERTED` | Currency conversion completed |\n| `PAYOUT_INITIATED` | Payout initiated from wallet (debit) |\n| `PAYOUT_FAILED` | Payout failed, funds returned to wallet (credit) |\n| `PAYOUT_REVERSED` | Payout reversed, funds returned to wallet (credit) |\n| `PAYOUT_SENT_TO_FAILED` | Previously sent payout moved to failed state |\n| `PAYOUT_FAILED_TO_SENT` | Previously failed payout moved to sent state |\n\n## 🔗 Resource References\n\nWhere 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.\n\n## 📄 Pagination\n\nResults 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.\n","tags":["Wallet Statement"],"summary":"List Lines","parameters":[{"description":"The Wallet Statement ID (stm-xxx)","name":"id","in":"path","required":true,"schema":{"type":"string"}},{"description":"The count of items returned as part of the pagination cursor iteration, minimum value is 1 and maximum 50","name":"paging_limit","in":"query","schema":{"type":"integer"}},{"description":"The base64 URL encoded cursor used to access the next set of paginated results","name":"paging_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessCollection"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/openapi.WalletStatementLine"}},"meta":{"$ref":"#/components/schemas/openapi.WalletStatementListLinesResponseMeta"}}}]}}}},"404":{"description":"Couldn't find any statement with the provided ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyNotFound"}}}},"409":{"description":"Statement is not ready yet, see [error codes](error-codes#statement_not_ready-http-409)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyStatementNotReady"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}},"/wallets":{"get":{"security":[{"Bearer":[]}],"description":"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.\n\nThis particular endpoint will return a comprehensive list of your active wallets, showcasing their associated currencies and the most recent updates on available balances.","tags":["Wallet"],"summary":"List","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/openapi.ResponseBodySuccessCollectionNoMeta"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"available":{"description":"The actual available balance","type":"string","example":"2000.99"},"balance":{"description":"The total balance yet to settle","type":"string","example":"2000.99"},"currency":{"description":"The ISO 4217 currency code associated with the wallet","type":"string","format":"iso4217","example":"KES"},"id":{"type":"string","format":"ksuid","example":"wlt-xxx"}}}}}}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/openapi.ResponseBodyInternalServerError"}}}}}}}},"servers":[{"url":"https://rest.sandbox.rafiki-api.com/v1"}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"openapi.LookupGetResponse":{"type":"object","properties":{"holder":{"type":"object","properties":{"name":{"description":"The payment account owner's registered full name at the banking entity","type":"string","example":"Mario Rossi"}},"x-order":"1"}}},"openapi.PayinCreateRequest":{"type":"object","properties":{"amount":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe intended amount to collect from either the payment_account_id or payment_account","type":"object","properties":{"currency":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"TZS"},"value":{"description":"<span style=\"color:#e95f6a;\">required</span>","type":"string","example":"2000.99"}}},"custom_id":{"description":"An optional unique custom id that can be used to reconcile payins with your own internal systems, this is particularly useful in the event of network failures.\n\nThe accepted format can include up to 64 characters, which may consist of both letters, digits, and the symbols \"-\" and \"_\".","type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"payment_account":{"description":"<span style=\"color:#e95f6a;\">required if payment_account_id is empty</span>\n\nYou 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 source for the payin request. If it already exists, we will simply retrieve it and utilize it, preventing the creation of duplicate accounts.","allOf":[{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateRequest"}]},"payment_account_id":{"description":"<span style=\"color:#e95f6a;\">required if payment_account is empty</span>\n\nThe payment account ID represents a pre-existing payment account that acts as the source for the payin.","type":"string","example":"pac-xxx"},"wallet_id":{"description":"The wallet ID to which to deposit money, if not provided, we will attempt to use the one that matches the provided currency amount.","type":"string","example":"wlt-xxx"}}},"openapi.PayinCreateResponse":{"type":"object","properties":{"amount":{"type":"object","properties":{"currency":{"description":"The currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"TZS"},"value":{"type":"string","example":"2000.99"}}},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"custom_id":{"type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"id":{"description":"The payin unique identifier","type":"string","example":"pyn-xxx"},"payment_account_id":{"description":"The source payment account sending funds","type":"string","example":"pac-xxx"},"state":{"type":"object","properties":{"code":{"description":"The state code signifies the overall status of a payin. For detailed information about the meaning of each state, please consult the lifecycle section above.","type":"string","enum":["PENDING","COLLECTED","SETTLED","FAILED"],"example":"PENDING"},"context":{"description":"Together with the \"code\" property, the \"context\" property offers additional context and information, whenever possible, about the specific state. For instance, if a payin fails, there are numerous reasons why this might occur. The \"context\" property will provide more detailed information in such cases.","type":"string"}}},"wallet_id":{"description":"The wallet ID to which the money will be deposited","type":"string","example":"wlt-xxx"}}},"openapi.PayinGetResponse":{"type":"object","properties":{"amount":{"type":"object","properties":{"currency":{"description":"The currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"TZS"},"value":{"type":"string","example":"2000.99"}}},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"custom_id":{"type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"id":{"description":"The payin unique identifier","type":"string","example":"pyn-xxx"},"payment_account_id":{"description":"The source payment account sending funds","type":"string","example":"pac-xxx"},"state":{"type":"object","properties":{"code":{"description":"The state code signifies the overall status of a payin. For detailed information about the meaning of each state, please consult the lifecycle section above.","type":"string","enum":["PENDING","COLLECTED","SETTLED","FAILED"],"example":"PENDING"},"context":{"description":"Together with the \"code\" property, the \"context\" property offers additional context and information, whenever possible, about the specific state. For instance, if a payin fails, there are numerous reasons why this might occur. The \"context\" property will provide more detailed information in such cases.","type":"string"}}},"wallet_id":{"description":"The wallet ID to which the money will be deposited","type":"string","example":"wlt-xxx"}}},"openapi.PaymentAccountGetOrCreateRequest":{"type":"object","properties":{"type":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nEither `MOBILE_MONEY`, `BANK_ACCOUNT`, `BANK_ACCOUNT_ROUTE` or `ALIAS`","type":"string","enum":["MOBILE_MONEY","BANK_ACCOUNT","BANK_ACCOUNT_ROUTE","ALIAS"],"x-order":"1"},"country":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe ISO 3166 alpha-2 country code in which the payment account is registered.","type":"string","format":"iso3166 alpha-2","x-order":"2","example":"KE"},"holder":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe individual (or business) in whose name the bank account is registered","type":"object","properties":{"name":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nEither the INDIVIDUAL full name or the BUSINESS registered legal name","type":"string","format":"^(?:[\\p{L}'\\-]+\\s*)+$"},"type":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe holder legal entity type, whether an INDIVIDUAL person or a BUSINESS","type":"string","enum":["INDIVIDUAL","BUSINESS"]}},"x-order":"3"},"mobile_money":{"type":"object","properties":{"number":{"description":"<span style=\"color:#e95f6a;\">required with type MOBILE_MONEY</span>\n\nThe actual phone number formatted as E.164","type":"string","format":"e164","example":"+254000000000"},"operator":{"description":"<span style=\"color:#e95f6a;\">required with type MOBILE_MONEY</span>\n\nThe telco network associated with the phone number. Each country allows only a subset of operators, this is documented [here](post_payment-accounts#mobile-money).","type":"string","enum":["SAFARICOM","AT","AIRTEL","VODACOM","TIGO","HALOTEL","TTCL","MTN","VODAFONE","MOOV","ORANGE","FREE","EXPRESSO","WAVE","BKASH","NAGAD","GCASH","MAYA","COINS","GRABPAY","EASYPAISA","JAZZCASH","UPAISA","SADAPAY","NAYAPAY","FINJA","PAYMAX"]}},"x-order":"4"},"bank_account":{"type":"object","properties":{"bank_id":{"description":"<span style=\"color:#e95f6a;\">required with type BANK_ACCOUNT</span>\n\nThe bank identifier representing the bank associated with the payment account","type":"string","format":"ksuid","example":"bnk-xxx"},"number":{"description":"<span style=\"color:#e95f6a;\">required with type BANK_ACCOUNT</span>\n\nThe actual bank account number (alphanum).","type":"string","format":"alphanum","example":"12345678"}},"x-order":"4"},"bank_account_route":{"type":"object","properties":{"code":{"description":"<span style=\"color:#e95f6a;\">required with type BANK_ACCOUNT_ROUTE</span>\n\nThe routing code representing the bank/branch associated with the payment account","type":"string","format":"alphanum","example":"CNRB0005800"},"number":{"description":"<span style=\"color:#e95f6a;\">required with type BANK_ACCOUNT_ROUTE</span>\n\nThe actual bank account number (alphanum).","type":"string","format":"alphanum","example":"12345678"}},"x-order":"5"},"alias":{"type":"object","properties":{"identifier":{"description":"<span style=\"color:#e95f6a;\">required with type ALIAS</span>\n\nThe unique payment handle/identifier within the alias network.","type":"string","example":"johndoe@ybl"},"network":{"description":"<span style=\"color:#e95f6a;\">required with type ALIAS</span>\n\nThe alias network the payment account belongs to.","type":"string","enum":["UPI"]}},"x-order":"6"}}},"openapi.PaymentAccountGetOrCreateResponse":{"type":"object","properties":{"id":{"description":"The newly created payment account unique identifier","type":"string","format":"iso3166 alpha-2","x-order":"0","example":"pac-xxx"},"type":{"type":"string","default":"MOBILE_MONEY","x-order":"1"},"country":{"type":"string","format":"iso3166 alpha-2","x-order":"2","example":"KE"},"holder":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["INDIVIDUAL","BUSINESS"]}},"x-order":"3"},"bank_account":{"type":"object","properties":{"bank_id":{"type":"string","format":"ksuid","example":"bnk-xxx"},"number":{"type":"string","format":"alphanum"}},"x-order":"4"},"bank_account_route":{"type":"object","properties":{"code":{"type":"string","format":"alphanum","example":"CNRB0005800"},"number":{"type":"string","format":"alphanum","example":"12345678"}},"x-order":"5"},"alias":{"type":"object","properties":{"identifier":{"type":"string","example":"johndoe@ybl"},"network":{"type":"string","enum":["UPI"]}},"x-order":"6"},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"mobile_money":{"type":"object","properties":{"number":{"type":"string","format":"e164","example":"+254000000000"},"operator":{"type":"string","enum":["SAFARICOM","AT","AIRTEL","VODACOM","TIGO","HALOTEL","TTCL","MTN","VODAFONE","MOOV","ORANGE","FREE","EXPRESSO","WAVE","BKASH","NAGAD","GCASH","MAYA","COINS","GRABPAY","EASYPAISA","JAZZCASH","UPAISA","SADAPAY","NAYAPAY","FINJA","PAYMAX"],"example":"SAFARICOM"}}}}},"openapi.PaymentAccountListResponseMeta":{"type":"object","properties":{"paging":{"type":"object","properties":{"cursors":{"type":"object","properties":{"after":{"type":"string","example":"cGFjLTJXTFhiOGJQNnNTN1FSdkE2QUZHcDdOaEdzNw=="}}},"next":{"type":"string","example":"https://rest.sandbox.rafiki-api.com/v1/payment-accounts?paging_after=cGFjLTJXTFhiOGJQNnNTN1FSdkE2QUZHcDdOaEdzNw%3D%3D&paging_limit=15"}}}}},"openapi.PayoutCreateRequest":{"type":"object","properties":{"amount":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe intended amount to send to either the payment_account_id or payment_account","type":"object","properties":{"currency":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"KES"},"value":{"description":"<span style=\"color:#e95f6a;\">required</span>","type":"string","example":"2000.99"}}},"custom_id":{"description":"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.\n\nThe accepted format can include up to 64 characters, which may consist of both letters, digits, and the symbols \"-\" and \"_\".","type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"on_behalf_of":{"description":"This field is required for integrators processing payments on behalf of another party. You must input the <strong>Legal Entity Name</strong> of the organization on behalf of whom you are processing payments.","type":"array","items":{"type":"string","format":".{1,200}"},"example":["[\"org-xxx\"]"]},"payment_account":{"description":"<span style=\"color:#e95f6a;\">required if payment_account_id is empty</span>\n\nYou 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.","allOf":[{"$ref":"#/components/schemas/openapi.PaymentAccountGetOrCreateRequest"}]},"payment_account_id":{"description":"<span style=\"color:#e95f6a;\">required if payment_account is empty</span>\n\nThe payment account ID represents a pre-existing payment account that acts as the recipient for the payout.","type":"string","example":"pac-xxx"},"purpose":{"description":"<span style=\"color:#e95f6a;\">required if payment_account country is GH,UG,EG,CI,SN or CM</span>\n\nThe purpose of the payout is a mandatory property that must be provided for compliance and reporting purposes.\nChoose one of the following predefined values that best describes the nature of the payout:\n\n<ul>\n<li><code>GOODS_PURCHASE</code>: Payments made for buying physical or digital goods.</li>\n<li><code>SERVICES_PAYMENT</code>: Payments made for services rendered, including professional services, consulting, and freelance work.</li>\n<li><code>INVOICE_PAYMENT</code>: Payments made to settle invoices issued for goods or services.</li>\n<li><code>LOAN_REPAYMENT</code>: Payments made towards repaying loans, including personal, auto, mortgage, and business loans.</li>\n<li><code>BILLS_PAYMENT</code>: Payments for recurring bills such as utilities, rent, insurance, and telecommunications.</li>\n<li><code>SALARY_AND_WAGES</code>: Disbursements made to employees for their salaries and wages.</li>\n<li><code>P2P_TRANSFER</code>: Domestic person-to-person transfers for sending money to friends, family, or acquaintances.</li>\n<li><code>REMITTANCE</code>: Cross-border person-to-person transfers for sending money to friends, family, or acquaintances.</li>\n<li><code>DONATION</code>: Payments made to charitable organizations or causes.</li>\n<li><code>GRANTS_AND_SCHOLARSHIPS</code>: Payments distributed as grants, scholarships, or other forms of financial aid.</li>\n<li><code>TRAVEL_AND_ACCOMMODATION</code>: Payments made for travel-related expenses, including flight bookings, hotel reservations, and car rentals.</li>\n<li><code>TAX_PAYMENT</code>: Payments made for settling taxes and duties.</li>\n<li><code>INSURANCE_PREMIUM</code>: Payments made towards insurance policies, including health, auto, and life insurance.</li>\n</ul>","type":"string","enum":["GOODS_PURCHASE","SERVICES_PAYMENT","INVOICE_PAYMENT","LOAN_REPAYMENT","BILLS_PAYMENT","SALARY_AND_WAGES","P2P_TRANSFER","REMITTANCE","DONATION","GRANTS_AND_SCHOLARSHIPS","TRAVEL_AND_ACCOMMODATION","TAX_PAYMENT","INSURANCE_PREMIUM"],"example":"REMITTANCE"},"sender":{"description":"An optional property for incorporating sender details. Please refer to the \"💡 **Compliance requirements**\" documentation above.","type":"object","properties":{"address":{"type":"object","properties":{"city":{"description":"<span style=\"color:#e95f6a;\">required if address is provided</span>","type":"string","example":"Roma"},"country":{"description":"<span style=\"color:#e95f6a;\">required if address is provided</span>\n\nThe ISO 3166 alpha-2 country code associated with the address.","type":"string","example":"IT"},"line_1":{"description":"<span style=\"color:#e95f6a;\">required if address is provided</span>","type":"string","example":"Piazza del Colosseo"},"line_2":{"type":"string","example":"1"},"line_3":{"type":"string","x-omitempty":true,"example":""},"postal_code":{"description":"<span style=\"color:#e95f6a;\">required if address is provided</span>\n\n⚠️ We enforce postal code validation for these following country codes : GB, US, PT, IE, MT, NG, NL, SK","type":"string","example":"00184"}}},"individual":{"type":"object","properties":{"dob":{"description":"Date of birth formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"1970-01-01"},"identity_document":{"type":"object","properties":{"country":{"description":"<span style=\"color:#e95f6a;\">required if identity_document is provided</span>\n\nThe ISO 3166 alpha-2 country code indicating the issuing country of the document.","type":"string","format":"ISO 3166 alpha-2","example":"IT"},"expires_on":{"description":"<span style=\"color:#e95f6a;\">required if identity_document is provided</span>\n\nDate formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2030-01-01"},"issued_on":{"description":"Date formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2020-01-01"},"number":{"description":"<span style=\"color:#e95f6a;\">required if identity_document is provided</span>","type":"string","example":"YA0000000"},"type":{"description":"<span style=\"color:#e95f6a;\">required if identity_document is provided</span>\n\nOne of `PASSPORT`, `DRIVING_LICENSE`, `NATIONAL_ID_CARD`, `RESIDENCE_PERMIT`","type":"string","enum":["PASSPORT","DRIVING_LICENSE","NATIONAL_ID_CARD","RESIDENCE_PERMIT"]}}}}},"name":{"description":"<span style=\"color:#e95f6a;\">required if sender is provided</span>\n\nThe individual full name or registered business legal name","type":"string","example":"Mario Rossi"},"type":{"description":"<span style=\"color:#e95f6a;\">required if sender is provided</span>\n\nEither `INDIVIDUAL` or `BUSINESS`","type":"string","enum":["INDIVIDUAL","BUSINESS"]}}},"wallet_id":{"description":"The wallet ID from which to disburse money, if not provided, we will attempt to use the one that matches the provided currency amount.","type":"string","example":"wlt-xxx"}}},"openapi.PayoutCreateResponse":{"type":"object","properties":{"amount":{"type":"object","properties":{"currency":{"description":"The currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"2000.99"}}},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"custom_id":{"type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"id":{"description":"The payout unique identifier","type":"string","example":"pyt-xxx"},"on_behalf_of":{"description":"This field is required for integrators processing payments on behalf of another party. You must input the <strong>Legal Entity Name</strong> of the organization on behalf of whom you are processing payments.","type":"array","items":{"type":"string"},"example":["[\"org-xxx\"]"]},"payment_account_id":{"description":"The recipient payment account receiving funds","type":"string","example":"pac-xxx"},"purpose":{"type":"string","enum":["GOODS_PURCHASE","SERVICES_PAYMENT","INVOICE_PAYMENT","LOAN_REPAYMENT","BILLS_PAYMENT","SALARY_AND_WAGES","P2P_TRANSFER","REMITTANCE","DONATION","GRANTS_AND_SCHOLARSHIPS","TRAVEL_AND_ACCOMMODATION","TAX_PAYMENT","INSURANCE_PREMIUM"],"example":"REMITTANCE"},"sender":{"type":"object","properties":{"address":{"type":"object","properties":{"city":{"type":"string","example":"Roma"},"country":{"description":"The ISO 3166 alpha-2 country code associated with the address.","type":"string","format":"ISO 3166 alpha-2","example":"IT"},"line_1":{"type":"string","example":"Piazza del Colosseo"},"line_2":{"type":"string","example":"1"},"line_3":{"type":"string","x-omitempty":true,"example":""},"postal_code":{"type":"string","example":"00184"}}},"individual":{"type":"object","properties":{"dob":{"description":"Date of birth formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"1970-01-01"},"identity_document":{"type":"object","properties":{"country":{"description":"The ISO 3166 alpha-2 country code indicating the issuing country of the document.","type":"string","format":"ISO 3166 alpha-2","example":"IT"},"expires_on":{"description":"Date formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2030-01-01"},"issued_on":{"description":"Date formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2020-01-01"},"number":{"type":"string","example":"YA0000000"},"type":{"type":"string","enum":["PASSPORT","DRIVING_LICENSE","NATIONAL_ID_CARD","RESIDENCE_PERMIT"]}}}}},"name":{"description":"The individual full name or registered business legal name","type":"string","example":"Mario Rossi"},"type":{"type":"string","enum":["INDIVIDUAL","BUSINESS"]}}},"state":{"type":"object","properties":{"code":{"description":"The state code signifies the overall status of a payout. For detailed information about the meaning of each state, please consult the lifecycle section above.","type":"string","enum":["PENDING","REVERSED","SENT","CANCELLED","FAILED"],"example":"PENDING"},"context":{"description":"Together with the \"code\" property, the \"context\" property offers additional context and information, whenever possible, about the specific state. For instance, if a payout fails, there are numerous reasons why this might occur. The \"context\" property will provide more detailed information in such cases.","type":"string"}}},"wallet_id":{"description":"The wallet ID from which the money will disburse","type":"string","example":"wlt-xxx"}}},"openapi.PayoutGetResponse":{"type":"object","properties":{"amount":{"type":"object","properties":{"currency":{"description":"The currency associated with the amount value, formatted according to ISO 4217","type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"2000.99"}}},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"custom_id":{"type":"string","format":"[a-zA-Z0-9-_]{1,64}","example":"custom-id-xxx"},"id":{"description":"The payout unique identifier","type":"string","example":"pyt-xxx"},"on_behalf_of":{"description":"This field is required for integrators processing payments on behalf of another party. You must input the <strong>Legal Entity Name</strong> of the organization on behalf of whom you are processing payments.","type":"array","items":{"type":"string"},"example":["[\"org-xxx\"]"]},"payment_account_id":{"description":"The recipient payment account receiving funds","type":"string","example":"pac-xxx"},"purpose":{"type":"string","enum":["GOODS_PURCHASE","SERVICES_PAYMENT","INVOICE_PAYMENT","LOAN_REPAYMENT","BILLS_PAYMENT","SALARY_AND_WAGES","P2P_TRANSFER","REMITTANCE","DONATION","GRANTS_AND_SCHOLARSHIPS","TRAVEL_AND_ACCOMMODATION","TAX_PAYMENT","INSURANCE_PREMIUM"],"example":"REMITTANCE"},"receipt":{"description":"The reference provided by the recipient account's actual bank or telco on a successful payout.\n\n> ⚠️\n> It's important to be aware that this information might not be accessible for every payout. If there's no way for us to obtain it, this property will be omitted entirely. Hence, we highly recommend implementing conditional checks to confirm the presence of this property.","type":"string","example":"ref-xxx (format changes depending on the telco/bank)"},"sender":{"type":"object","properties":{"address":{"type":"object","properties":{"city":{"type":"string","example":"Roma"},"country":{"description":"The ISO 3166 alpha-2 country code associated with the address.","type":"string","format":"ISO 3166 alpha-2","example":"IT"},"line_1":{"type":"string","example":"Piazza del Colosseo"},"line_2":{"type":"string","example":"1"},"line_3":{"type":"string","x-omitempty":true,"example":""},"postal_code":{"type":"string","example":"00184"}}},"individual":{"type":"object","properties":{"dob":{"description":"Date of birth formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"1970-01-01"},"identity_document":{"type":"object","properties":{"country":{"description":"The ISO 3166 alpha-2 country code indicating the issuing country of the document.","type":"string","format":"ISO 3166 alpha-2","example":"IT"},"expires_on":{"description":"Date formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2030-01-01"},"issued_on":{"description":"Date formatted as yyyy-mm-dd","type":"string","format":"yyyy-mm-dd","example":"2020-01-01"},"number":{"type":"string","example":"YA0000000"},"type":{"type":"string","enum":["PASSPORT","DRIVING_LICENSE","NATIONAL_ID_CARD","RESIDENCE_PERMIT"]}}}}},"name":{"description":"The individual full name or registered business legal name","type":"string","example":"Mario Rossi"},"type":{"type":"string","enum":["INDIVIDUAL","BUSINESS"]}}},"state":{"type":"object","properties":{"code":{"description":"The state code signifies the overall status of a payout. For detailed information about the meaning of each state, please consult the lifecycle section above.","type":"string","enum":["PENDING","REVERSED","SENT","CANCELLED","FAILED"],"example":"PENDING"},"context":{"description":"Together with the \"code\" property, the \"context\" property offers additional context and information, whenever possible, about the specific state. For instance, if a payout fails, there are numerous reasons why this might occur. The \"context\" property will provide more detailed information in such cases.","type":"string"}}},"wallet_id":{"description":"The wallet ID from which the money will disburse","type":"string","example":"wlt-xxx"}}},"openapi.PayoutListResponseMeta":{"type":"object","properties":{"paging":{"type":"object","properties":{"cursors":{"type":"object","properties":{"after":{"type":"string","example":"dHJ4LTJXTFhiOGJQNnNTN1FSdkE2QUZHcDdOaEdzNw=="}}},"next":{"type":"string","example":"https://rest.sandbox.rafiki-api.com/v1/payouts?paging_after=dHJ4LTJXTFhiOGJQNnNTN1FSdkE2QUZHcDdOaEdzNw%3D%3D&paging_limit=10"}}}}},"openapi.ResponseBodyIdempotencyConflict":{"type":"object","properties":{"code":{"description":"Can be either `IDEMPOTENCY_RACE` or `IDEMPOTENCY_KEY_ALREADY_USED`","type":"string","example":"IDEMPOTENCY_RACE"},"message":{"description":"E.g. \"Idempotency key already in use\"","type":"string","example":"Idempotency key already in use"}}},"openapi.ResponseBodyInternalServerError":{"type":"object","properties":{"code":{"description":"`INTERNAL_SERVER_ERROR`","type":"string","example":"INTERNAL_SERVER_ERROR"},"message":{"description":"E.g. \"An internal error has occurred.\"","type":"string","example":"An internal error has occurred."}}},"openapi.ResponseBodyLookupAccountNotFound":{"type":"object","properties":{"code":{"description":"`LOOKUP_ACCOUNT_NOT_FOUND`","type":"string","example":"LOOKUP_ACCOUNT_NOT_FOUND"},"message":{"description":"E.g. \"Invalid bank account number, or, syntactically valid, but not registered with any banking entity\"","type":"string","example":"the provided account identifier {'xxxxxxxxx'} couldn't be looked up"}}},"openapi.ResponseBodyNotFound":{"type":"object","properties":{"code":{"description":"`NOT_FOUND`","type":"string","example":"NOT_FOUND"},"message":{"description":"E.g. \"The resource you are looking for cannot be found.\"","type":"string","example":"The resource you are looking for cannot be found."}}},"openapi.ResponseBodyPayoutPaymentAccountTemporarilyUnavailable":{"type":"object","properties":{"code":{"description":"`PAYOUT_BANK_TEMPORARILY_UNAVAILABLE`","type":"string","example":"PAYOUT_BANK_TEMPORARILY_UNAVAILABLE"},"message":{"description":"E.g. \"Payout to this bank is not available.\"","type":"string","example":"Payout to this bank is not available."}}},"openapi.ResponseBodyStatementNotReady":{"type":"object","properties":{"code":{"description":"`STATEMENT_NOT_READY`","type":"string","example":"STATEMENT_NOT_READY"},"message":{"description":"E.g. \"Statement is not ready yet\"","type":"string","example":"Statement is not ready yet"}}},"openapi.ResponseBodySuccessCollection":{"type":"object","properties":{"data":{"type":"array","items":{}},"meta":{}}},"openapi.ResponseBodySuccessCollectionNoMeta":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"openapi.ResponseBodySuccessNoMeta":{"type":"object","properties":{"data":{}}},"openapi.ResponseBodyValidationFailed":{"type":"object","properties":{"code":{"description":"`VALIDATION_FAILED`","type":"string","example":"VALIDATION_FAILED"},"errors":{"type":"object","properties":{"fields":{"description":"Every key corresponds to the name of a property that has not passed validation. The value associated with each key is an array of strings that serves to provide a descriptive explanation of the requirements for that particular property and the reasons for its failure.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"message":{"description":"E.g. \"Validation failed.\"","type":"string","example":"Validation failed."}}},"openapi.ResponseBodyWalletInsufficientBalance":{"type":"object","properties":{"code":{"description":"`WALLET_INSUFFICIENT_BALANCE`","type":"string","example":"WALLET_INSUFFICIENT_BALANCE"},"message":{"description":"E.g. \"Wallet '{wlt-xxx}' doesn't have enough balance\"","type":"string","example":"wallet '{wlt-xxx}' doesn't have enough balance"}}},"openapi.WalletStatementCreateRequest":{"type":"object","properties":{"period":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe time period covered by the statement","type":"object","properties":{"from":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe start date/time of the statement period. Must be a valid date (YYYY-MM-DD) or RFC3339 datetime string with hour precision (no minutes or seconds).","type":"string","format":"RFC 3339","example":"2025-01-01T00:00:00Z"},"to":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe end date/time of the statement period. Must be a valid date (YYYY-MM-DD) or RFC3339 datetime string with hour precision (no minutes or seconds).","type":"string","format":"RFC 3339","example":"2025-01-31T23:00:00Z"}}},"wallet_id":{"description":"<span style=\"color:#e95f6a;\">required</span>\n\nThe wallet ID for which to generate the statement","type":"string","example":"wlt-xxx"}}},"openapi.WalletStatementLine":{"type":"object","properties":{"amount":{"description":"The amount of the transaction","type":"object","properties":{"currency":{"type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"100.00"}}},"posted_at":{"description":"The date/time when this transaction was posted to the wallet","type":"string","format":"RFC 3339","example":"2025-01-15T10:00:00Z"},"resource":{"description":"Reference to the associated resource (payout, collection, etc.)","allOf":[{"$ref":"#/components/schemas/openapi.WalletStatementLineResource"}]},"running_balance":{"description":"The running balance after this transaction","type":"object","properties":{"currency":{"type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"5100.00"}}},"type":{"description":"The type of transaction\n\n<ul>\n<li><code>COLLECTION_COLLECTED</code>: Funds collected into the wallet</li>\n<li><code>COLLECTION_CONVERTED</code>: Collected funds converted to wallet currency</li>\n<li><code>CONVERSION_INITIATED</code>: Currency conversion initiated</li>\n<li><code>CONVERSION_CONVERTED</code>: Currency conversion completed</li>\n<li><code>PAYOUT_INITIATED</code>: Payout initiated from wallet</li>\n<li><code>PAYOUT_FAILED</code>: Payout failed, funds returned to wallet</li>\n<li><code>PAYOUT_REVERSED</code>: Payout reversed, funds returned to wallet</li>\n<li><code>PAYOUT_SENT_TO_FAILED</code>: Previously sent payout moved to failed state</li>\n<li><code>PAYOUT_FAILED_TO_SENT</code>: Previously failed payout moved to sent state</li>\n</ul>","type":"string","enum":["COLLECTION_COLLECTED","COLLECTION_CONVERTED","CONVERSION_INITIATED","CONVERSION_CONVERTED","PAYOUT_INITIATED","PAYOUT_FAILED","PAYOUT_REVERSED","PAYOUT_SENT_TO_FAILED","PAYOUT_FAILED_TO_SENT"],"example":"PAYOUT_INITIATED"}}},"openapi.WalletStatementLineResource":{"type":"object","properties":{"custom_id":{"description":"The custom ID if one was provided when the resource was created","type":"string","example":"custom-id-xxx"},"id":{"description":"The resource ID (e.g., payout ID, collection ID)","type":"string","example":"pyt-xxx"}}},"openapi.WalletStatementListLinesResponseMeta":{"type":"object","properties":{"paging":{"type":"object","properties":{"cursors":{"type":"object","properties":{"after":{"type":"string","example":"d2x0LXN0bXQtbGluZS14eHg="}}},"next":{"type":"string","example":"https://rest.sandbox.rafiki-api.com/v1/wallet-statements/stm-xxx/lines?paging_after=d2x0LXN0bXQtbGluZS14eHg%3D&paging_limit=10"}}}}},"openapi.WalletStatementResponse":{"type":"object","properties":{"closing_balance":{"description":"The wallet balance at the end of the statement period","type":"object","properties":{"currency":{"type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"7500.00"}}},"created_at":{"type":"string","format":"RFC 3339","example":"2006-01-02T15:04:05Z07:00"},"id":{"description":"The statement unique identifier","type":"string","example":"stm-xxx"},"period":{"description":"The time period covered by the statement","type":"object","properties":{"from":{"type":"string","format":"RFC 3339","example":"2025-01-01T00:00:00Z"},"to":{"type":"string","format":"RFC 3339","example":"2025-01-31T23:00:00Z"}}},"starting_balance":{"description":"The wallet balance at the start of the statement period","type":"object","properties":{"currency":{"type":"string","format":"ISO 4217","example":"KES"},"value":{"type":"string","example":"5000.00"}}},"state":{"type":"object","properties":{"code":{"description":"The state code signifies the overall status of a statement.","type":"string","enum":["PENDING","READY","FAILED"],"example":"PENDING"},"context":{"description":"Additional context about the statement state, if available","type":"string"}}},"wallet_id":{"description":"The wallet ID associated with this statement","type":"string","example":"wlt-xxx"}}}}}}