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}}"
}

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"
}

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}}

PreviousBankNextCompany Statements

Last updated