# Initiate a Payout

Disburse funds directly to a customer's mobile money wallet or bank account. Payouts are processed asynchronously — the API queues the disbursement and notifies your server via webhook once the funds are settled.

* [ ] Mobile Money 
* [ ] Bank Transfer

**How It Works**

Before initiating a payout, you may need to look up reference IDs depending on your disbursement method. Both flows share the same endpoint — only the request body differs.

1. **Fetch Prerequisites:**

* For mobile money, call GET `/v1/countries` to get the country\_id.
* For bank transfers, also call GET **/payment/banks?country=GH** to get the bank\_id.

2. **Initiate the Payout**\
   POST to `/v1/payment/payouts/process` with the amount, destination, and transfer method. Vesicash queues the disbursement and returns a payout reference.
3. **Receive Webhook**

   Vesicash sends a POST notification to your `webhook_url` when the payout status changes to successful or failed.

   <br>

#### <mark style="color:green;">POST:</mark> v1/payment/payouts/process

#### Headers

| Name       | Type   | Description              |
| ---------- | ------ | ------------------------ |
| secret-key | string | Your Vesicash secret key |
| public-key | string | Your Vesicash public key |

#### Request Body — Common Parameters

These parameters apply to all payout types regardless of `transfer_to` value.

* amount (number): The amount to be disburse.&#x20;
* countryId (string): The Vesicash identifier for the payout country. Call `GET` /`v1/countries` to retrieve available country IDs.
* transfer\_to(string): The disbursement method. Determines which additional fields are required. e.g `mobile_money` or `bank`.
* webhook\_url(string): A publicly accessible HTTPS URL where Vesicash will POST the payout status notification.
* narration (string: optional): A brief description or note regarding the payout. This helps in identifying the purpose of the transaction.
* momo\_phone\_number (string, optional): The mobile money phone number to which the payout will be sent. If this is not provided, the payment will be credited to the merchant's momo account.

#### Additional Parameters by Transfer Type

The fields below are required depending on the value of `transfer_to`.

{% tabs %}
{% tab title="mobile\_money" %}
momo\_phone\_number(string): The mobile money phone number to receive the payout. Provide the full number in E.164 format — country code followed by the subscriber number, with no +, spaces, or dashes. eg 260999993000
{% endtab %}

{% tab title="bank" %}
bank\_id(string): The unique Vesicash identifier for the destination bank. Call `GET /v1/banks` to retrieve the list of supported banks and their IDs for the selected country.

account\_number(string):  The recipient's bank account number. Must be a valid account number at the specified bank.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**ℹ️ Fetching Bank IDs**

Use the `GET /v1/banks` endpoint with the relevant country\_id to retrieve a list of available banks and their corresponding bank\_id values before making a bank payout request.
{% endhint %}

#### Request

For example, you can make a post request to the endpoint above and pass in the raw json data below to create a one-off transaction.

```
//Mobile Money Payout


{
    
    "amount":123,
    "countryId": "{{zambia_country_id}}",
    "transfer_to":"mobile_money"   // bank
    "momo_phone_number": "260********",
    "webhook_url": "https://webhook.site/99a3cf82-d235-00000000000000000000",
    "narration":"testing" //optional
}
```

```
// Bank Transfer Payout

{
  "amount": 123,
  "countryId": "zambia_country_id",
  "transfer_to": "bank",
  "bank_id": "zmb_zanaco_001",             // from GET /v1/banks
  "account_number": "1234567890",
  "webhook_url": "https://yourapp.com/webhooks/vesicash",
  "narration": "March commission payout"           // optional
}
```

#### Response

```
{
    "status": "success",
    "code": 200,
    "message": "payout queued successfully",
    "data": {
        "amount": 26,
        "message": "Payout is being processed by the provider",
        "reference": "PY_6c663231b************",
        "status": "processing"
    }
}
```