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/
{
"client": {
"email": "example@gmail.com",
"phone": "256700123123",
"country": "UG",
// "full_name": "Jane Rose",
// "personal_code": "10231",
// "tax_number": "70002307552",
// "city": "Kampala",
// "street_address": "Ntinda",
// "zip_code": "124538",
// "state": "Nakawa"
},
"payment": {
"currency": "UGX",
"amount": "500",
"description": "Test Payout"
},
"reference": "Your unique transaction reference",
"brand_id": "{{BrandId}}"
}{
"id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "initialized",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": null,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": null,
"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": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.created",
"updated_on": 1747308302,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
}
],
"transaction_data": {
"flow": "payform",
"extra": {},
"country": "",
"attempts": [],
"payment_method": ""
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": null,
"recipient_card_country": "",
"payout_method_whitelist": null
}Name
Type
Description
Authorization*
Bearer {{secret key}}
Content-Type*
String
application/json
201: Created
The transaction ID in JSON response is then used to execute request(Step 2).
Step 2 - Execute
Utilize the {{execution_url}} obtained in step 1 to submit a second request.
POST {{execution_url}}
{
"payout_type": "mobile"
}// If excute is successful
{
"status": "pending",
"details": {
"return_code": "200",
"message": "Transaction received for processing",
"transaction": {
"status": "pending",
"internal_reference": "35F1496D9E17485A800D4847F22BC720"
}
}
}// If you have insufficient balance
{
"status": "error",
"error": {
"code": "insufficient_funds",
"message": "Insufficient funds to proceed with operation."
}
}
Name
Type
Description
Content-Type*
String
application/json
200: OK
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": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"type": "payout",
"client": {
"cc": [],
"bcc": [],
"city": "",
"email": "example@gmail.com",
"phone": "256700123123",
"state": "",
"country": "UG",
"zip_code": "",
"bank_code": "",
"full_name": "",
"brand_name": "",
"legal_name": "",
"tax_number": "",
"client_type": null,
"bank_account": "123456789013",
"personal_code": "",
"shipping_city": "",
"shipping_state": "",
"street_address": "",
"delivery_methods": [
{
"method": "email",
"options": {}
},
{
"method": "text_message",
"options": {
"custom_message": ""
}
}
],
"shipping_country": "",
"shipping_zip_code": "",
"registration_number": "",
"shipping_street_address": ""
},
"status": "success",
"is_test": false,
"payment": {
"amount": 500,
"paid_on": 1747308344,
"currency": "UGX",
"fee_amount": 0,
"net_amount": 500,
"description": "Test Payout",
"is_outgoing": true,
"payment_type": "payout",
"pending_amount": 0,
"remote_paid_on": 1747308344,
"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": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
"created_on": 1747308302,
"event_type": "payout.success",
"updated_on": 1747308344,
"sender_name": "",
"execution_url": "https://gate.paytota.com/po/7c4ea981-55b1-418a-be23-ea9f5f3e1a91/paytota_proxy/",
"status_history": [
{
"status": "initialized",
"timestamp": 1747308302
},
{
"status": "pending",
"timestamp": 1747308339
},
{
"status": "success",
"timestamp": 1747308344
}
],
"transaction_data": {
"flow": "server_to_server",
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"attempts": [
{
"flow": "server_to_server",
"error": null,
"extra": {
"webhook_payload": {
"bank": {
"bank_code": "SBICUGKX",
"bank_name": "Stanbic Bank",
"account_name": "Jane Rose",
"account_number": "123456789012"
},
"client": {
"city": "",
"email": "example@gmail.com",
"state": "",
"zip_code": "",
"full_name": "",
"tax_number": "",
"personal_code": "",
"street_address": ""
},
"message": "Transaction successful",
"return_code": "200",
"transaction": {
"amount": 500,
"mobile": "256700123123",
"status": "successful",
"country": "UG",
"currency": "UGX",
"operator": "SANDBOX",
"description": "",
"destination": "bank",
"transaction_type": "payout",
"external_reference": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
"internal_reference": "35F1496D9E17485A800D4847F22BC720",
"operator_reference": "7d795431-a622-42c5-88a3-1354a90621d2"
}
}
},
"country": "",
"client_ip": "",
"fee_amount": 0,
"successful": true,
"payment_method": "paytota_proxy",
"processing_time": 1747308344
}
],
"payment_method": "paytota_proxy"
},
"reference_generated": "159e12f9-17b7-410d-a7a8-7644e1f1c6b9",
"recipient_card_brand": "paytota_proxy",
"recipient_card_country": "",
"payout_method_whitelist": null
}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/json
Authorization*
String
Bearer {{secret key}}
Last updated