Payment

When a payment event occurs, 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
`payment.received`	Payment has been successfully completed and settled.
`payment.failed`	Payment could not be completed.

Payload Fields

string

required

The event type. One of payment.received or payment.failed.

string

required

Unique identifier for the transaction.

string

required

The payment method used, e.g. ussd.

string

required

ISO currency code, e.g. TZS.

object

required

Show properties

string

Channel name, e.g. AIRTEL-MONEY, TIGO-PESA.

string | null

Channel-level transaction reference. null if the transaction did not reach the channel.

object

required

Show properties

string

Gross payment amount, e.g. 1,000.00. Always present.

string

Platform fee deducted. Only present on payment.received.

string

Net amount settled to your account (value minus fee). Only present on payment.received.

object

required

Show properties

string

Customer’s phone number.

string | null

Customer’s full name as returned by the channel. May be null if the channel did not provide it.

object

Arbitrary key-value pairs provided at payment creation, echoed back as-is. Use these to correlate events with records in your system.

string

Human-readable reason for the failure. Only present on payment.failed.

string

required

ISO 8601 UTC timestamp of when the payment was created.

string

required

ISO 8601 UTC timestamp of the last status update.

string

required

ISO 8601 UTC timestamp of when this webhook was dispatched.

Example Payloads

payment.received
payment.failed

{
  "event": "payment.received",
  "amount": {
    "fee": "10.00",
    "value": "1,000.00",
    "settled": "990.00"
  },
  "channel": {
    "name": "AIRTEL-MONEY",
    "reference": "MP260712.1803.R20406"
  },
  "customer": {
    "full_name": "JOHN DOE",
    "phone_number": "255682123456"
  },
  "metadata": {
    "order_id": "128128",
    "customer_note": "Test payment"
  },
  "transaction_id": "70ea1299-72f4-43c7-b65f-84d10af8547c",
  "transaction_mode": "ussd",
  "transaction_currency": "TZS",
  "timestamp": "2026-07-12T15:07:28.653212Z",
  "created_at": "2026-07-12T15:03:07.000000Z",
  "updated_at": "2026-07-12T15:07:28.000000Z"
}

{
  "event": "payment.failed",
  "amount": {
    "value": "1,000.00"
  },
  "channel": {
    "name": "TIGO-PESA",
    "reference": null
  },
  "customer": {
    "full_name": null,
    "phone_number": "255682123456"
  },
  "metadata": {
    "order_id": "128128",
    "customer_note": "Test payment"
  },
  "failure_reason": "Transaction timedout",
  "transaction_id": "fc6f023d-7cd1-4eb7-be83-ada32691a6c9",
  "transaction_mode": "ussd",
  "transaction_currency": "TZS",
  "timestamp": "2026-07-12T15:06:59.272837Z",
  "created_at": "2026-07-12T15:01:54.000000Z",
  "updated_at": "2026-07-12T15:06:59.000000Z"
}

Getting started

Webhooks

Events

Payload Fields

Example Payloads

​Events

​Payload Fields

​Example Payloads

Events

Payload Fields

Example Payloads