> ## Documentation Index
> Fetch the complete documentation index at: https://api.tandapay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and payloads

> The webhook envelope, every event type and example payloads.

## Envelope

Every webhook has the same three top-level fields.

```json theme={null}
{
  "event": "transaction_updated",
  "data": { },
  "timestamp": "2026-10-28T09:14:22.100Z"
}
```

**event** `string`

The event name. See [Event types](#event-types).

**data** `object`

The transaction the event is about. See [Fields in data](#fields-in-data).

**timestamp** `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

**transactionId** `string` *required*

Tanda's ID for the transaction.

**externalReference** `string` *required*

The unique reference you sent.

**status** `string` *required*

`pending`, `successful` or `failed`.

**type** `string` *required*

`deposit`, `withdrawal` or `refund`.

**method** `string`

The rail: `momo` or `bank`.

**stepRequired** `string`

A step the customer must complete: `otp` or `redirect`.

**redirectUrl** `string`

Where to send the customer when `stepRequired` is `redirect`.

**thirdPartyReference** `string`

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

**note** `string`

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

**amount** `number`

Amount in KES, when included.

**currency** `string`

`KES`, when included.

**originalTransactionId** `string`

Refunds only. The deposit being refunded.

**completedAt** `string`

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

**failureReason** `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**
>
> ```json theme={null}
> {
>   "event": "transaction_created",
>   "data": {
>     "transactionId": "aB3dE5fG7hJ9kL1mN2pQ",
>     "status": "pending",
>     "type": "deposit",
>     "externalReference": "order_10045",
>     "method": "momo"
>   },
>   "timestamp": "2026-10-28T09:13:58.000Z"
> }
> ```

> **Deposit successful**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "event": "payout_created",
>   "data": {
>     "transactionId": "pY7tR5eW3qA1sD9fG2hJ",
>     "status": "pending",
>     "type": "withdrawal",
>     "externalReference": "payout_5531"
>   },
>   "timestamp": "2026-10-28T11:00:02.000Z"
> }
> ```

> **Payout successful**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "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**
>
> ```json theme={null}
> {
>   "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"
> }
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.