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

201: Created

The transaction ID in JSON response is then used to execute request(Step 2).

Request

{
    "client": {
        "email": "[e-mail]",
        "phone": "751123456"
    },
    "payment": {
        "currency": "UGX",
        "amount": "500",
        "description": "Test Payout Airtel"
    },
    "reference": "Your unique transaction reference",
    "brand_id": "{{BrandId}}"
}

Response

{
  "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": "[e-mail]",
    "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

200: OK

Request (UGX)

{
    "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.

Request (KES)

{
    "accountNumber": "254705881346",
    "accountInstitution": "MPESA",
    "paymentMode": "MOBILE_MONEY",
    "country": "Kenya"
}

The networks available are below.

• imalipay_payouts

Response

// 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": "[e-mail]",
    "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}}

200: OK