> For the complete documentation index, see [llms.txt](https://docs.paytota.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.paytota.com/payments/mobile-money/disbursement-payout.md).

# 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.

<mark style="color:green;">`POST`</mark> `{base url}/api/v1/payouts/`

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization<mark style="color:red;">\*</mark> |        | Bearer **`{{secret key}}`** |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json            |

{% tabs %}
{% tab title="201: Created " %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The transaction ID in JSON response is then used to execute request(Step 2).
{% endhint %}

{% tabs %}
{% tab title="Request" %}

<pre class="language-json5"><code class="lang-json5"><strong>{
</strong>    "client": {
        "email": "example@gmail.com",
        "phone": "751123456"
    },
    "payment": {
        "currency": "UGX",
        "amount": "500",
        "description": "Test Payout Airtel"
    },
    "reference": "Your unique transaction reference",
    "brand_id": "{{BrandId}}"
}
</code></pre>

{% endtab %}

{% tab title="Response" %}

```json5
{
  "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"
}
```

{% endtab %}
{% endtabs %}

### Step 2 - Execute

## Using the transaction ID received in Step 1, this method is then queried by sending a json request to execute payout.&#x20;

<mark style="color:green;">`POST`</mark> `{base url}/po/{id}/{network}/`

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request (UGX)" %}

```json5
{
    "phone":"751123456"
}
```

{% hint style="info" %}
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.
{% endhint %}
{% endtab %}

{% tab title="Request (KES)" %}

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

{% hint style="info" %}
The networks available are below.

* imalipay\_payouts
  {% endhint %}
  {% endtab %}

{% tab title="Response" %}

```json5
// If excute is successful

{
  "detail": "pending",
  "status": "pending"
}
```

```json5
// If you have insufficient balance

{
  "status": "error",
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient funds to proceed with operation."
  }
}

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You will receive a callback on your webhook URL regarding the status of the transaction

```
Successful transaction  (status = success)
Failed transaction (status = error)
```

{% endhint %}

<details>

<summary>Callback Example</summary>

```json5
{
  "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": ""
}
```

</details>

### Check Disbursement/Payout Status

## This API method is used to query the payouts/disbursement transaction status using the transaction ID.

<mark style="color:blue;">`GET`</mark> `{base url}/api/v1/payouts/{id}/`

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/js              |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer **`{{secret key}}`** |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}