Payout

When a payout succeeds or fails, the platform sends an HTTP POST request to your configured callback URL. Each request contains an event field identifying the notification type.

If your API token has a passphrase configured, every request includes a Pesahub-Signature header — an HMAC over the raw payload. See Verify a Checksum for validation steps.

Events

Event	Description
`payout.completed`	Payment has been settled to the beneficiary.
`payout.failed`	Payout could not be processed.

Payload Fields

string

required

The event type. One of payout.completed or payout.failed.

string

required

Unique identifier for the transaction.

string

required

The payout channel type, e.g. mobile or bank.

string

required

ISO currency code, e.g. TZS.

object

required

Show properties

string

Channel name, e.g. airtel, mpesa, or a bank identifier.

string

Channel-level transaction reference.

object

required

Show properties

string

Formatted payout amount, e.g. 1,000.00.

string

required

Your platform’s payout reference.

object

required

Hide properties

Mobile payout

string

Beneficiary’s phone number.

string

Mobile network, e.g. airtel, mpesa.

string

Beneficiary’s full name.

Bank payout

string

Beneficiary’s bank account number.

string

Name of the beneficiary’s bank.

string

BIC/SWIFT code of the beneficiary’s bank.

object

Arbitrary key-value pairs you attached to the payout request.

string | null

ISO 8601 timestamp of when the payout was settled. null for failed payouts.

string

required

ISO 8601 timestamp of when the payout was created.

string

required

ISO 8601 timestamp of when this webhook was dispatched.

Example Payloads

payout.completed
payout.failed

{
  "event": "payout.completed",
  "transaction_id": "a04a0d76-bbbf-4838-b626-6f15555b08ff",
  "transaction_mode": "mobile",
  "transaction_currency": "TZS",
  "channel": {
    "name": "airtel",
    "reference": "PAY7C550724L"
  },
  "amount": {
    "value": "1,000.00"
  },
  "payout_reference": "TJVLCKHK3LEO",
  "beneficiary": {
    "phone_number": "255682123456",
    "phone_network": "airtel",
    "full_name": "JOHN DOE"
  },
  "metadata": {
    "order_id": "order12345",
    "note": "someone wants money"
  },
  "paid_at": "2026-08-16T18:44:28.000000Z",
  "created_at": "2026-08-16T18:43:32.000000Z",
  "timestamp": "2026-08-16T18:44:29.625184Z"
}

{
  "event": "payout.failed",
  "transaction_id": "8f3a1c2e9-4838-b626-6f15555b08ff",
  "transaction_mode": "mobile",
  "transaction_currency": "TZS",
  "channel": {
    "name": "mpesa",
    "reference": "CPTXN987654"
  },
  "amount": {
    "value": "1,000.00"
  },
  "payout_reference": "PYT0260810001",
  "beneficiary": {
    "phone_number": "255712345678",
    "phone_network": "mpesa",
    "full_name": "JOHN DOE"
  },
  "metadata": {
    "your_custom_key": "your_custom_value"
  },
  "paid_at": null,
  "created_at": "2026-08-16T10:12:00.000000Z",
  "timestamp": "2026-08-16T10:15:24.000000Z"
}

Getting started

Webhooks

Events

Payload Fields

Example Payloads

​Events

​Payload Fields

​Example Payloads

Events

Payload Fields

Example Payloads