Bank Payout

Step 1 - Initiate

This API method is used to initiate a disbursement/payout request for which you will receive a JSON response.

POST {base url}/api/v1/payouts/

{
    "client": {
        "email": "[email protected]",
        "phone": "256700123123",
        "bank_account": "123456789012",
        "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": "[email protected]",
    "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
}

Step 2 - Execute

Utilize the {{execution_url}} obtained in step 1 to submit a second request.

POST {{execution_url}}

{
    "payout_type": "bank",
    "bank_name": "Stanbic Bank",
    "bank_code": "SBICUGKX",
    "bank_account_name": "Jane Rose",
    "bank_account_number": "123456789012"
}

// If excute is successful

{
    "status": "pending",
    "details": {
        "return_code": "200",
        "message": "Transaction received for processing",
        "transaction": {
            "status": "pending",
            "internal_reference": "35F1496D9E17485A800D4847F22BC720"
        }
    }
}

{
  "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": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91",
  "type": "payout",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "",
    "email": "[email protected]",
    "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": "[email protected]",
          "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": "[email protected]",
              "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 Token

Token*

String

{{secret key}}

PreviousBank NextCompany Statements

Last updated 6 months ago

{ "id": "7c4ea981-55b1-418a-be23-ea9f5f3e1a91", "type": "payout", "client": { "cc": [], "bcc": [], "city": "", "email": "[email protected]", "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": "[email protected]", "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": "[email protected]", "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 }