Payment Status and Webhooks - PCX Developer Docs

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

To receive webhook notifications, send your webhook endpoint URL to info@pcxpay.com. Our team will register it on your account before you go live.

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

{
  "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.
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.

​Status lifecycle

​Checking status manually

​Webhooks

​Events

​Example payload

​Webhook requirements

Status lifecycle

Checking status manually

Webhooks

Events

Example payload

Webhook requirements