Events and payloads

Envelope

Every webhook has the same three top-level fields.

{
  "event": "transaction_updated",
  "data": { },
  "timestamp": "2026-10-28T09:14:22.100Z"
}

string

The event name. See Event types.

object

The transaction the event is about. See Fields in data.

string

When the event was created, ISO 8601.

Event types

Event	Sent when
`transaction_created`	A charge, checkout payment or refund is created.
`transaction_updated`	Its status changes, or the customer needs to take a step (`stepRequired`).
`payout_created`	A payout is created.
`payout_updated`	A payout’s status changes.

New event types may be added. Return 2xx for any you don’t recognise.

Transaction types

`data.type`	Meaning
`deposit`	Money in: checkout, mobile money or bank transfer.
`withdrawal`	Money out: a payout. Shown as `withdrew` on transaction records.
`refund`	A refund of an earlier deposit.

Statuses

`data.status`	Meaning
`pending`	In progress. Not an outcome.
`successful`	Done; money moved. The only status to fulfil on.
`failed`	Didn’t complete. `note` or `failureReason` explains why.

A stepRequired update keeps the status at pending. It isn’t a failure.

Fields in data

string

required

Tanda’s ID for the transaction.

string

required

The unique reference you sent.

string

required

pending, successful or failed.

string

required

deposit, withdrawal or refund.

string

The rail: momo or bank.

string

A step the customer must complete: otp or redirect.

string

Where to send the customer when stepRequired is redirect.

string

The network or bank reference, such as an M-PESA receipt number.

string

Extra detail, often the reason for a failure. For display and logs only; don’t branch on it.

number

Amount in KES, when included.

string

KES, when included.

string

Refunds only. The deposit being refunded.

string

Successful payouts only. When the payout completed, ISO 8601.

string

Failed payouts only. Why the payout failed. For display and logs only.

Optional fields are left out rather than sent as null, so parse defensively.

Example payloads

Deposit created

{
  "event": "transaction_created",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "pending",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo"
  },
  "timestamp": "2026-10-28T09:13:58.000Z"
}

Deposit successful

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "successful",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "thirdPartyReference": "TJS4K2LM9P"
  },
  "timestamp": "2026-10-28T09:14:22.100Z"
}

Deposit failed

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "failed",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "note": "The User cannot be reached by STK Push"
  },
  "timestamp": "2026-10-28T09:15:01.000Z"
}

Deposit needs an OTP

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "pending",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "stepRequired": "otp"
  },
  "timestamp": "2026-10-28T09:14:05.000Z"
}

Deposit needs a redirect

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "pending",
    "type": "deposit",
    "externalReference": "order_10045",
    "method": "momo",
    "stepRequired": "redirect",
    "redirectUrl": "https://example.com/approve/abc"
  },
  "timestamp": "2026-10-28T09:20:11.000Z"
}

Payout created

{
  "event": "payout_created",
  "data": {
    "transactionId": "pY7tR5eW3qA1sD9fG2hJ",
    "status": "pending",
    "type": "withdrawal",
    "externalReference": "payout_5531"
  },
  "timestamp": "2026-10-28T11:00:02.000Z"
}

Payout successful

{
  "event": "payout_updated",
  "data": {
    "transactionId": "pY7tR5eW3qA1sD9fG2hJ",
    "status": "successful",
    "type": "withdrawal",
    "externalReference": "payout_5531",
    "thirdPartyReference": "TJT8Q1ZX4C",
    "completedAt": "2026-10-28T11:00:09.000Z"
  },
  "timestamp": "2026-10-28T11:00:09.400Z"
}

Payout failed

{
  "event": "payout_updated",
  "data": {
    "transactionId": "pY7tR5eW3qA1sD9fG2hJ",
    "status": "failed",
    "type": "withdrawal",
    "externalReference": "payout_5531",
    "failureReason": "The recipient's number is invalid or not registered for Mobile Money."
  },
  "timestamp": "2026-10-28T11:00:07.000Z"
}

Refund successful

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "rF4gH6jK8lM0nP2qR4sT",
    "originalTransactionId": "aB3dE5fG7hJ9kL1mN2pQ",
    "status": "successful",
    "type": "refund",
    "externalReference": "refund_order_10045",
    "amount": 1500,
    "currency": "KES",
    "method": "momo"
  },
  "timestamp": "2026-10-28T10:02:11.000Z"
}

Get started

Accept payments

Send payouts

Webhooks

Go live

Events and payloads

Envelope

Event types

Transaction types

Statuses

Fields in data

Example payloads

​Envelope

​Event types

​Transaction types

​Statuses

​Fields in data

​Example payloads

Envelope

Event types

Transaction types

Statuses

Fields in data

Example payloads