> For the complete documentation index, see [llms.txt](https://docs.pretium.africa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pretium.africa/payout-payin/payout-and-payin.md). # Payout & Payin Payout and Payin functions work the same way as off-ramp and on-ramp transactions. They use the same request body structure, except **`transaction_hash`** & **`chain`** are not included in payout/payin requests. See the On-Ramp / Off-Ramp section for more details. #### Disbursement This endpoint calls the Pretium payment protocol to verify that the payment has been made and releases the equivalent fiat amount. | Name | Type | Description | | --------------- | ------- | ------------------------------------------------------- | | type | String | Type of payment, MOBILE, BUY\_GOODS & PAYBILL | | shortcode | String | Recipient mobile number, till number or paybill number | | account\_number | String | Required if type is PAYBILL | | amount | Integer | Amount to disburse | | mobile\_network | String | Supported mobile network ie Safaricom | | callback\_url | URL | URL to receive payment notification | ``` POST {{url}}/{{currencyCode}}/disburse ``` {% tabs %} {% tab title="Request Body" %} ``` { "shortcode": "0700123456", "amount": "50", "type": "MOBILE", "mobile_network": "Safaricom", // Airtel (required only when type is MOBILE) "callback_url": "https://pretium.africa/b2c/log-test" } ``` {% endtab %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "Message", "data": { "status": "PENDING", "transaction_code": "DDM6D", "message": "Success! Processing payment..." } } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} #### Collection This endpoint calls the Pretium payment protocol to initiate cash collection from the user, confirm receipt via mobile money or bank transfer. ``` POST {{url}}/{{currencyCode}}/collect ``` {% tabs %} {% tab title="Request Body" %} ``` { "shortcode": "0743312265", "amount": "20", "mobile_network": "Safaricom",//Airtel "callback_url": "https://pretium.africa/b2c/log-test" } ``` {% endtab %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "Disburse initiated", "data": { "status": "PENDING", "transaction_code": "TSALX", "message": "Success! Processing payment." } } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} #### Supported Banks Get a list of all supported banks supported by Pretium APIs. ``` POST {{url}}/{{currencyCode}}/banks ``` {% tabs %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "List of banks", "data": [ { "Code": "247247", "Name": "Equity Bank" }, ] } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} #### Bank Transfer This endpoint calls the Pretium payment protocol to verify that the payment has been made and settles the payment to the recipient's bank account. ``` POST {{url}}/{{currencyCode}}/bank-transfer ``` {% tabs %} {% tab title="Request Body" %} ``` { "amount": "500", "account_number": "001918181", "bank_code": "247247", } ``` {% endtab %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "Message", "data": { "status": "PENDING", "transaction_code": "DDM6D", "message": "Success! Processing payment..." } } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} #### Validation This endpoint validates a phone number and returns the registered individual's name as provided by Mobile Network Operators (MNOs). Note: Reliability varies by country, so avoid heavy dependence on this endpoint for phone number validation. ``` POST {{url}}/{{currencyCode}}/validation ``` {% tabs %} {% tab title="Request Body" %} ``` { "shortcode": "0700123456", "type": "MOBILE", "network": "Safaricom" } ``` {% endtab %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "Validation results", "data": { "status": "COMPLETE", "shortcode": "0700123456", "public_name": "JOHN DOE" } } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} #### Status Fetch a transaction using its transaction code. ``` POST {{url}}/{{currencyCode}}/status ``` {% tabs %} {% tab title="Request Body" %} ``` { "transaction_code": "fg464gggshshkkk" } ``` {% endtab %} {% tab title="200 - Success" %} ``` { "code": 200, "message": "Transaction", "data": { "id": 51215, "transaction_code": "045c1753-4e5b-4fa8-997b-ee52b78a96fa", "status": "COMPLETE", "amount": "20", "type": "MOBILE", "shortcode": "0700123456", "account_number": null, "public_name": "JOHN DOE", "receipt_number": "TIMCW5AK69", "category": "DISBURSEMENT", "message": "Transaction processed successfully.", "currency_code": "KES", "created_at": "2025-09-22T08:08:18.000000Z" } } ``` {% endtab %} {% tab title="400 - Bad Request" %} ``` { "code": 400, "message": "Failed - Bad Request" } ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pretium.africa/payout-payin/payout-and-payin.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.