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

# Payment Status and Webhooks

> How to track payment status and receive real-time notifications

## Status lifecycle

```
initiated → pending → processing → completed
                                 ↘ failed
```

| Status       | Description                                          |
| ------------ | ---------------------------------------------------- |
| `initiated`  | Payment request created, awaiting customer action    |
| `pending`    | Customer has opened the link and started the payment |
| `processing` | Payment is being processed by the bank               |
| `completed`  | Payment successfully settled                         |
| `failed`     | Payment failed or was cancelled                      |

***

## Checking status manually

Do not poll for status — use webhooks to receive updates in real time.

If you need to retrieve the current status of a payment:

```
GET /payments/{payment_id}
GET /payments/transaction/{transaction_id}
```

***

## Webhooks

<Note>
  To receive webhook notifications, send your webhook endpoint URL to [info@pcxpay.com](mailto:info@pcxpay.com). Our team will register it on your account before you go live.
</Note>

PCX sends a `POST` request to your registered webhook endpoint on every payment status change. Register your webhook endpoint in the PCX Dashboard before going live.

### Events

| Event               | Description                                 |
| ------------------- | ------------------------------------------- |
| `payment.initiated` | Payment created and accepted for processing |
| `payment.settled`   | Payment successfully settled                |
| `payment.failed`    | Payment failed or cancelled                 |

### Example payload

```json theme={null}
{
  "event_id": "9f0a1c2e-...",
  "event_type": "payment.settled",
  "event_category": "payment",
  "event_object_id": "pay_abc123",
  "event_object_status": "completed",
  "occurred_at": "2026-09-04T10:30:00+00:00",
  "event_object": {
    "reference": "pay_abc123",
    "transaction_id": "txn_xyz789",
    "narration": "Payment",
    "source": {
      "amount": { "value": "100.00", "currency": "GBP" }
    },
    "destination": {
      "amount": { "value": "100.00", "currency": "GBP" },
      "method": "transfer",
      "beneficiary": { "name": "Recipient Name" }
    }
  },
  "metadata": {}
}
```

### Webhook requirements

* **Validate signatures** — always verify webhook signatures before processing events. See [Webhooks](/guides/essentials/webhooks).
* **Respond quickly** — your endpoint must return a `2xx` status within 30 seconds.
* **Idempotency** — PCX retries failed deliveries. Implement idempotency using `event_id` to avoid processing the same event twice.