Webhook Payload Structure

Understand the structure of webhook event payloads.

Payload Format

All webhook payloads are JSON-encoded and include the following fields:

{
  "merchant_id": "1234567890",
  "event_id": "evt_1234567890abcdef",
  "event_type": "payment_succeeded",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "pay_1234567890abcdef",
      "merchant_id": "1234567890",
      "status": "succeeded",
      "amount": 5000,
      "amount_received": 5000,
      "currency": "USD",
      "payment_method": "card",
      "created": "2024-01-22T10:30:00Z",
      "metadata": {
        "order_id": "order_123"
      }
    }
  },
  "timestamp": "2024-01-22T10:30:05Z"
}

Payload Fields

Field	Type	Description
`merchant_id`	string	Merchant account that owns the event.
`event_id`	string	Unique identifier for this event.
`event_type`	string	The type of event (see Event Types).
`content`	object	Tagged event resource. Includes `type` and `object`.
`content.type`	string	Resource type for the event, such as `payment_details`, `refund_details`, `dispute_details`, `mandate_details`, `payout_details`, or `subscription_details`.
`content.object`	object	The resource payload. Its fields vary by `content.type`.
`timestamp`	string	ISO 8601 timestamp of when the webhook was sent.

Process each event_id once. For payment events, update local orders using content.object.payment_id or your own order reference such as content.object.metadata.order_id when present.

Error Fields (Failed Payments)

When a payment fails, content.object carries additional error fields that describe why. These fields are present on failed payments (for example event_type: payment_failed with status: failed) and are null on successful payments.

Two kinds of error information are reported: flat summary fields for a quick read, and a nested error_details.issuer_details object with the raw response from the cardholder's bank.

{
  "event_type": "payment_failed",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "152e072a22d7406a933acdb34000a814",
      "status": "failed",

      "unified_code": "UE_9000",
      "unified_message": "Something went wrong",
      "issuer_error_code": "51",
      "issuer_error_message": "Not sufficient funds",

      "error_details": {
        "issuer_details": {
          "code": "51",
          "message": "Not sufficient funds",
          "network_details": {
            "name": "Visa",
            "advice_code": null,
            "advice_message": "Not sufficient funds"
          }
        }
      }
    }
  }
}

Which field carries the issuer (bank) decline code? Use content.object.error_details.issuer_details.code — this is the raw code returned by the cardholder's bank (for example "51" = insufficient funds). The same value is mirrored at the flat field content.object.issuer_error_code. For a human-readable reason, use error_details.issuer_details.message or error_details.issuer_details.network_details.advice_message.

Summary fields

Flat fields on content.object that give a quick summary of the failure.

Field	Type	Description
`unified_code`	string \| null	ReliancePays's unified error category, such as `UE_9000`.
`unified_message`	string \| null	ReliancePays's unified, customer-safe message.
`issuer_error_code`	string \| null	Raw decline code from the issuing bank (mirrors `error_details.issuer_details.code`).
`issuer_error_message`	string \| null	Raw decline message from the issuing bank.

`error_details.issuer_details`

The response from the cardholder's issuing bank. This is where the bank's raw decline code lives.

Field	Type	Description
`code`	string \| null	Raw decline code from the issuing bank, such as `"51"`.
`message`	string \| null	Raw decline reason from the issuing bank.
`network_details.name`	string \| null	Card network, such as `Visa` or `Mastercard`.
`network_details.advice_code`	string \| null	Network advice code guiding whether/how to retry, when available.
`network_details.advice_message`	string \| null	Human-readable network advice, when available.

Headers

Webhook requests include the following headers:

Header	Description
`Content-Type`	Always `application/json`
`User-Agent`	Webhook client user agent
`X-Webhook-Signature-512`	HMAC-SHA512 signature of the raw request body, when webhook signing is configured