Skip to main content

Disbursements

Overview​

To disburse funds, you can use the POST /api/disbursements endpoint.

The endpoint requires a X-API-KEY header with your API key. See Getting Your API Keys for instructions on how to obtain your API key.

The key field is optional and can be used to identify the disbursement.

POST /api/disbursements
{
  "amount": 1,
  "method": "MPESA",
  "details": {
    "to": "254700000000",
    "accountType": "MOBILE"
  },
  "currency": "KES",
  "key": "..."
}
Response:
{
  "date": "2024-05-13T06:39:27.311Z",
  "data": {
    "message": "Withdrawal successful",
    "id": "...",
    "key": "...",
    "status": "success"
  }
}

Withdrawal charges​

Use GET /api/disbursements/charges to get the withdrawal charges.

The endpoint requires a X-API-KEY header with your API key. See Getting Your API Keys for instructions on how to obtain your API key.

Response:
{
  "date": "2024-05-15T13:21:47.154Z",
  "data": {
    "networks": [
      {
        "id": "MPESA",
        "name": "MPESA",
        "logo": "https://littleimages.blob.core.windows.net/walletproviders/KENYA/MPESA.png",
        "minimumAmount": 50,
        "maximumAmount": 100000
      }
    ],
    "charges": [
      {
        "networkId": "MPESA",
        "amount": 1000,
        "charges": 50
      },
      {
        "networkId": "MPESA",
        "amount": 2000,
        "charges": 100
      },
      {
        "networkId": "MPESA",
        "amount": 3000,
        "charges": 150
      },
      {
        "networkId": "MPESA",
        "amount": 5000,
        "charges": 170
      },
      {
        "networkId": "MPESA",
        "amount": 100000,
        "charges": 200
      }
    ]
  }
}

Disbursement Status​

To get the status of a disbursement, use the GET /api/disbursements/:key endpoint.

The :key is the key can be set to the key that you set when calling the disbursement endpoint, or the id returned when you disburse funds

Response:
{
  "date": "2024-05-13T06:39:27.311Z",
  "data": {
    "id": "...",
    "status": "success",
    "amount": 1,
    "key": "...",
    "method": "MPESA",
    "attempts": [
      {
        "id": "...",
        "status": "success",
        "amount": 1,
        "key": "...",
        "method": "MPESA"
      }
    ]
  }
}