Skip to main content
Set a webhook_url on a payment (or checkout) and Orqex POSTs a JSON event to it on every lifecycle change. This is the reliable way to learn a payment’s final status.

​
Events

​
payment.completed
event
The payment succeeded.
​
payment.failed
event
All attempts failed.
​
payment.expired
event
The intent expired.
​
payment.refunded
event
Fully refunded.
​
payment.partially_refunded
event
Partially refunded.
​
payment.attempt.completed
event
An attempt succeeded.
​
payment.attempt.failed
event
An attempt failed.
​
payment.attempt.action_required
event
An attempt needs customer action.
The event name is also sent in the X-Payment-Event header, with X-Payment-Id carrying the payment id.

​
Payload and handler

{
  "event": "payment.completed",
  "payment": {
    "id": "TRX1A2B3C4D",
    "amount": { "value": 5000, "formatted": "50.00 XOF", "currency": "XOF" },
    "status": "completed",
    "metadata": { "order_id": "1024" }
  },
  "attempt": { "id": "att_...", "status": "completed", "method_code": "momo_mtn", "is_fallback": false },
  "customer": { "id": "cus_...", "email": "[email protected]" },
  "timestamp": "2026-06-08T12:00:00+00:00"
}

​
Handling rules

  • Respond with 2xx quickly; do slow work asynchronously.
  • Orqex retries failed deliveries (up to 5 attempts).
  • Events are at-least-once — key your processing on payment.id + event.
Deliveries to a per-payment webhook_url are not signed. Re-fetch the payment from the API and act on that authoritative status (shown above). For signed deliveries, register a project webhook endpoint — each has a signing secret and an x-orqex-signature header you can verify.