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.

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

2. Receive Webhook

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

POST: 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.

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

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

bank

ℹ️ 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.

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