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

# Payload

> JSON schema and examples for webhook notifications.

We deliver `POST` requests with a JSON body to your callback URL.

## Top-level structure

```json theme={null}
{
  "status": "SUCCESS",
  "code": "102",
  "description": "Payment completed successfully",
  "results": {
    "result_code": "0",
    "result_description": "The service request is processed successfully.",
    "amount": 100,
    "total_charges": 10,
    "total_amount": 100,
    "account": "254708374149",
    "transaction_reference": "295877",
    "payment_uuid": "413283551145761444",
    "external_reference": "3C1HH10ZU8",
    "time_processed": "2026-01-07T09:48:08.8485958",
    "validation_hash": "16b70a72ab3abddd1a2ed3db533317be9785fa553beafb563d205cec5a693b6c",
    "metadata": {}
  }
}
```

**Fields**

* `status` (`string`): High-level outcome - e.g., `CREATED`, `PENDING`, `SUCCESS`, `FAILED`, `ESCALATED`, `EXPIRED`, `REFUNDED`, `REVERSED`.
* `code` (`string`): Machine code corresponding to `status` (e.g., `102` for `SUCCESS`).
* `description` (`string`): Human-friendly explanation.
* `results` (`object`): Detailed result set:
  * `result_code`, `result_description`: Processor/rail outcome.
  * Monetary fields: `amount`, `total_charges`, `total_amount`.
  * Ids: `transaction_reference` (your client reference), `payment_uuid` (Waftpay reference), `external_reference` (network/MNO reference if present).
  * `msisdn` (if applicable), `time_processed` (ISO-8601 UTC), `metadata` (optional).
  * `validation_hash`: Integrity string (see **Verify Signature**).

> **Note:** `client_reference` in other pages refers to this same `transaction_reference` field.

## Status codes

| status      | code    |
| ----------- | ------- |
| CREATED     | 100     |
| PENDING     | 101     |
| **SUCCESS** | **102** |
| FAILED      | 103     |
| ESCALATED   | 104     |
| EXPIRED     | 105     |
| REFUNDED    | 106     |
| REVERSED    | 107     |

These codes map to the payment lifecycle and are consistent across webhook events.