Disbursement/Payout
Step 1 - Initiate
This API method is used to initiate an a disbursement/payout request for which you will receive a JSON response.
POST {base url}/api/v1/payouts/
Headers
Name
Type
Description
Authorization*
Bearer {{secret key}}
Content-Type*
String
application/json
The transaction ID in JSON response is then used to execute request(Step 2).
{
"client": {
"email": "example@gmail.com",
"phone": "751123456"
},
"payment": {
"currency": "UGX",
"amount": "500",
"description": "Test Payout Airtel"
},
"reference": "Your unique transaction reference",
"brand_id": "{{BrandId}}"
}{
"payment": {
"is_outgoing": true,
"payment_type": "payout",
"amount": 500,
"currency": "UGX",
"net_amount": 500,
"fee_amount": 0,
"pending_amount": 0,
"pending_unfreeze_on": null,
"description": "Test paytota",
"paid_on": null,
"remote_paid_on": null,
"owned_bank_account_id": null,
"owned_bank_account": null,
"owned_bank_code": null
},
"client": {
"client_type": null,
"email": "test@example.com",
"phone": "700123123",
"full_name": "",
"personal_code": "",
"legal_name": "",
"brand_name": "",
"registration_number": "",
"tax_number": "",
"bank_account": "",
"bank_code": "",
"street_address": "",
"city": "",
"zip_code": "",
"country": "",
"state": "",
"shipping_street_address": "",
"shipping_city": "",
"shipping_zip_code": "",
"shipping_country": "",
"shipping_state": "",
"cc": [],
"bcc": [],
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
]
},
"transaction_data": {
"payment_method": "",
"flow": "payform",
"extra": {},
"country": "",
"attempts": []
},
"reference_generated": "141",
"reference": "",
"status": "initialized",
"status_history": [
{
"status": "initialized",
"timestamp": 1673249360
}
],
"sender_name": "",
"recipient_card_country": "",
"recipient_card_brand": null,
"execution_url": "https://gate.paytota.com/po/809a581f-dcb0-4be4-9917-514c81f381c5/airtel/",
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"is_test": false,
"user_id": null,
"created_on": 1673249360,
"updated_on": 1673249360,
"type": "payout",
"id": "809a581f-dcb0-4be4-9917-514c81f381c5"
}Step 2 - Execute
Using the transaction ID received in Step 1, this method is then queried by sending a json request to execute payout.
POST {base url}/po/{id}/{network}/
Headers
Name
Type
Description
Content-Type*
String
application/json
{
"phone":"751123456"
}The networks available are below.
airtel
mtnmomo
When submitting a phone number for Airtel, exclude the prefix. For example, use 751123456. For MTN Mobile Money, ensure the phone number includes the prefix 256. For instance, use 256784000111.
{
"accountNumber": "254705881346",
"accountInstitution": "MPESA",
"paymentMode": "MOBILE_MONEY",
"country": "Kenya"
}The networks available are below.
imalipay_payouts
// If excute is successful
{
"detail": "pending",
"status": "pending"
}// If you have insufficient balance
{
"status": "error",
"error": {
"code": "insufficient_funds",
"message": "Insufficient funds to proceed with operation."
}
}
You will receive a callback on your webhook URL regarding the status of the transaction
Successful transaction (status = success)
Failed transaction (status = error)Callback Example
{
"id": "2eb911cc-2541-4f8c-9fa5-22c10ad33280",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "test@example.com",
"phone": "700123123",
"country": "",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "",
"personal_code": "",
"shipping_city": "",
"street_address": "",
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "success",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": 1668084960,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test paytota",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": 1668084960,
"owned_bank_code": null,
"owned_bank_account": null,
"pending_unfreeze_on": null,
"owned_bank_account_id": null
},
"user_id": null,
"brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
"reference": "",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1668084945,
"event_type": "payout.success",
"updated_on": 1668084960,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/2eb911cc-2541-4f8c-9fa5-22c10ad33280/airtel/",
"status_history": [
{
"status": "initialized",
"timestamp": 1668084945
},
{
"status": "success",
"timestamp": 1668084960
}
],
"transaction_data": {
"flow": "server_to_server",
"extra": {},
"country": "",
"attempts": [
{
"flow": "server_to_server",
"error": null,
"extra": {},
"country": "",
"client_ip": "",
"fee_amount": 0,
"successful": true,
"payment_method": "airtel",
"processing_time": 1668084960
}
],
"payment_method": "airtel"
},
"reference_generated": "104",
"recipient_card_brand": "airtel",
"recipient_card_country": ""
}Check Disbursement/Payout Status
This API method is used to query the payouts/disbursement transaction status using the transaction ID.
GET {base url}/api/v1/payouts/{id}/
Headers
Name
Type
Description
Content-Type*
String
application/js
Authorization*
String
Bearer {{secret key}}
Last updated