Skip to main content

​
Event Overview

Event Type: PAYMENT_FAILED
Category: Payment
Description: Payment transaction has failed This webhook is triggered when a payment is marked FAILED (after a payment failed webhook/callback is received).

​
When the webhook is sent

  • Payment failed flow: After a payment failed webhook/callback is received, the payment is updated to FAILED and the webhook is created.
  • The webhook is created only if your merchant account (or parent, for sub-merchants) has an active API credential with a non-empty webhook URL.

​
Delivery Details

AttributeValue
HTTP methodPOST
URLThe webhook URL configured on your merchant account’s API credentials
Content-Typeapplication/json
Timeout10 seconds
RetriesUp to 5 delivery attempts (backoff: 1 min, 5 min, 15 min, 60 min)

​
Headers

HeaderDescription
Content-Typeapplication/json
User-AgentEximpe-Webhook/1.0
X-Webhook-EventPAYMENT_FAILED
X-Webhook-TimestampUnix timestamp (string) at the time of the request
X-Webhook-SignatureHMAC-SHA256 signature of the request body (JSON string with keys sorted, no extra whitespace), using your API key as the secret. Hex-encoded.
Signature verification (recommended):
Compute HMAC-SHA256(encryption_key, raw_body) where raw_body is the exact UTF-8 request body as received. Compare the hex result with the X-Webhook-Signature header to ensure the webhook is from the platform and unchanged.

​
Payload Schema

{
  "event_type": "PAYMENT_FAILED",
  "event_time": "2025-02-12T10:31:00.123456Z",
  "version": "2.0.0",
  "sequence_number": "660e8400-e29b-41d4-a716-446655440001",
  "data": {
    "payment_id": "770e8400-e29b-41d4-a716-446655440003",
    "order_id": "660e8400-e29b-41d4-a716-446655440001",
    "status": "FAILED",
    "message": "Payment declined by bank",
    "mop_type": "CARD",
    "bank_ref_num": "",
    "payment_completed_at": null,
    "utr": null,
    "virtual_account_id": null
  }
}

​
Field Specifications

​
event_type
string
required
Always "PAYMENT_FAILED" for this webhook event
​
event_time
string
required
ISO 8601 datetime when the webhook event was createdExample: "2025-02-12T10:31:00.123456Z"
​
version
string
required
Envelope version (e.g. “1.0”)
​
sequence_number
string
required
Unique identifier for this webhook event (UUID), useful for idempotencyExample: "660e8400-e29b-41d4-a716-446655440001"
​
data
object
required
Payment request details (payment_id, order_id, status, message, mop_type, bank_ref_num, payment_completed_at, utr, virtual_account_id)

​
What to Do When You Receive This Webhook

  1. Respond with HTTP 2xx (e.g. 200 OK) as soon as you have accepted the payload, so the platform marks the delivery as successful and does not retry.
  2. Verify the signature using your API key and the raw request body (HMAC-SHA256, hex) to ensure authenticity.
  3. Use data.payment_id and data.order_id to reconcile with your system or fetch more details from the Partner API.