PAYMENT FAILED

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

Attribute	Value
HTTP method	`POST`
URL	The webhook URL configured on your merchant account’s API credentials
Content-Type	`application/json`
Timeout	10 seconds
Retries	Up to 5 delivery attempts (backoff: 1 min, 5 min, 15 min, 60 min)

Headers

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Eximpe-Webhook/1.0`
`X-Webhook-Event`	`PAYMENT_FAILED`
`X-Webhook-Timestamp`	Unix timestamp (string) at the time of the request
`X-Webhook-Signature`	HMAC-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",
    "amount": 1000,
    "bank_ref_num": null,
    "extended_status": "FAILED",
    "payment_message": null,
    "payment_completed_at": null,
    "utr": null,
    "virtual_account_id": null,
    "subscription_id": null,
    "merchant_reference_id": "S2SIOAW7W4"
  }
}

Field Specifications

Root Level Fields
Data Object Fields

string

required

Always "PAYMENT_FAILED" for this webhook event

string

required

ISO 8601 datetime when the webhook event was createdExample: "2025-02-12T10:31:00.123456Z"

string

required

Envelope version (e.g. “2.0.0”)

string

required

Unique identifier for this webhook event (UUID), useful for idempotencyExample: "660e8400-e29b-41d4-a716-446655440001"

object

required

Payment request details (payment_id, order_id, status, message, mop_type, amount, bank_ref_num, extended_status, payment_message, payment_completed_at, utr, virtual_account_id, subscription_id, merchant_reference_id)

string

required

UID of the paymentExample: "770e8400-e29b-41d4-a716-446655440003"

string

required

UID of the order for this paymentExample: "660e8400-e29b-41d4-a716-446655440001"

string

required

Payment status (FAILED for failed payments)Example: "FAILED"

string

required

Failure reason or message from the paymentExample: "Payment declined by bank"

string

required

Method of payment typeExample: "CARD"

number

required

Payment amountExample: 1000

string

Bank reference number (if any); typically null for failed paymentsExample: null

string

required

Detailed status code for the paymentExample: "FAILED"

string

Additional processor-level message; may be null

string

ISO 8601 datetime when payment completed; may be null for failed paymentsExample: null

string

UTR of the payment (if any); may be empty or nullExample: null

string

Virtual account ID of the MerchantVBA (if this payment is linked to a VBA); otherwise nullExample: null

string

Subscription ID if this payment is linked to a subscription mandate; otherwise null

string

required

Your reference ID for the orderExample: "S2SIOAW7W4"

What to Do When You Receive This Webhook

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.
Verify the signature using your API key and the raw request body (HMAC-SHA256, hex) to ensure authenticity.
Use data.payment_id and data.order_id to reconcile with your system or fetch more details from the Partner API.

Order

Payment

Card Tokens

Merchant

Settlement

Refund

Subscriptions

Payment Links

Virtual Bank Accounts

Utilities

Webhooks

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

What to Do When You Receive This Webhook

​Event Overview

​When the webhook is sent

​Delivery Details

​Headers

​Payload Schema

​Field Specifications

​What to Do When You Receive This Webhook

Event Overview

When the webhook is sent

Delivery Details

Headers

Payload Schema

Field Specifications

What to Do When You Receive This Webhook