WEBHOOK EVENTS

Payments

Subscribe to payment lifecycle events and reconcile every state transition.

Payments Webhook Events

Payment events are snapshots of the payment when a lifecycle change occurred. A later event for the same payment can contain a newer state, so process transitions by payment ID rather than by delivery order.

Webhook request headers

Every webhook delivery includes headers that describe the request and help your server process retries safely. Header names are case-insensitive.

Example headers

Content-Type: application/json
X-FiatPe-Timestamp: 1788075601
X-FiatPe-Idempotency: event_reference_xxxxxxxxxxxxxxxx
X-FiatPe-Secret: your_webhook_secret

Header	Description
`Content-Type`	Always `application/json`. Parse the request body as JSON only after applying your authentication checks.
`X-FiatPe-Timestamp`	Unix timestamp, in seconds, representing when FiatPe created the delivery request.
`X-FiatPe-Idempotency`	A stable delivery key derived from the event reference. Store it with a unique constraint so a retried or duplicate webhook does not repeat the business action.
`X-FiatPe-Secret`	Included when a secret is configured for the webhook endpoint. Compare it with the secret stored securely on your server and reject a mismatch.

Keep the webhook secret confidential.

Read it from the request header on your backend. Do not expose it in frontend code, source control, application logs, or error responses.

List of Payments Webhook Events

Event	Triggered when	Recommended action
`payment.authorized`	The customer and issuing institution authorise the payment.	Wait for capture/final success unless your FiatPe configuration treats authorisation as final.
`payment.captured`	Funds are successfully captured for the payment.	Verify order, amount, currency, and status before fulfilment.
`payment.failed`	The payment attempt cannot be completed.	Record the failure safely and offer an appropriate customer retry path.

Payment lifecycle and event ordering

payment.authorized→payment.captured

A failed attempt can be followed by a successful retry. Do not reject a later verified success only because an earlier failure was received. Apply valid forward transitions using the current authoritative state.

{
  "mid": "mid_XXXXXXXXXX",
  "event": "payment.captured",
  "entity": "event",
  "contains": [
    "payment"
  ],
  "payload": {
    "payment": {
      "id": "pay_123456789",
      "fee": 200,
      "tax": 36,
      "vpa": "aftab@upi",
      "bank": null,
      "email": "aftab@mail.com",
      "amount": 10000,
      "entity": "payment",
      "method": "upi",
      "status": "captured",
      "wallet": null,
      "contact": "9960245621",
      "currency": "INR",
      "metadata": {},
      "order_id": "order_123456789",
      "created_at": 1788075600,
      "error_description": null,
      "acquirer_data": {
        "rrn": "626543219876",
        "account_type": "bank account"
      }
    }
  },
  "created_at": 1788075601
}

Card network and type values

For card payments, use the values inside the card object to identify the card network and funding type. Values are returned in lowercase.

Field	Example values	Description
`card.network`	`rupay`, `visa`, `mastercard`, `diners`, `amex`	Card network identified for the payment.
`card.type`	`credit card`, `debit card`, `prepaid card`	Funding type identified for the card.

These values can expand as additional networks and card types are supported. Treat unknown values as valid strings and avoid rejecting a webhook solely because a new value is returned.

Handling guidance

Key state updates by FiatPe payment ID and retain the related order ID.
Authenticate the webhook before trusting any payload field.
Treat authorisation as provisional unless capture is not required for your configuration.
Make success processing idempotent across Checkout callbacks, redirects, polling, and webhooks.
Preserve failure code, reason, source, and step for support without exposing sensitive data.