WEBHOOK EVENTS

Order

Subscribe to order lifecycle events and process paid orders safely.

Orders Webhook Events

Subscribe to order events when your business workflow is based on the overall order state. A paid order can include the associated order and payment snapshot so your backend can reconcile both identifiers.

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 Orders Webhook Events

Event	Triggered when	Recommended action
`order.partially_paid`	A partial payment is received and the order still has an amount due.	Update the paid and pending amounts, but do not fulfil the order as fully paid.
`order.paid`	The amount due for an order becomes zero after a successful payment.	Verify the payment and fulfil the order exactly once.
`order.cancelled`	The order is cancelled before its outstanding amount is fully paid.	Stop new payment attempts and preserve any payment/refund reconciliation required for the order.

Order Paid

order.paid represents the order-level completion signal. The related successful payment can also produce a payment event. Your integration should deduplicate business fulfilment across both paths.

{
  "mid": "mid_XXXXXXXXXX",
  "entity": "event",
  "event": "order.paid",
  "contains": [
    "payment",
    "order"
  ],
  "payload": {
    "payment": {
      "id": "pay_xxxxxxxxxxxxxxxx",
      "fee": 0,
      "tax": 0,
      "method": "upi",
      "bank": null,
      "card": null,
      "wallet": null,
      "vpa": "customer@upi",
      "acquirer_data": {
        "rrn": null
      },
      "email": null,
      "amount": 5000,
      "entity": "payment",
      "status": "captured",
      "contact": null,
      "currency": "INR",
      "metadata": {},
      "order_id": "order_xxxxxxxxxxxxxxxx",
      "created_at": 1788174184,
      "error_description": null
    },
    "order": {
      "id": "order_xxxxxxxxxxxxxxxx",
      "amount": 5000,
      "entity": "order",
      "status": "created",
      "attempts": 1,
      "currency": "INR",
      "method": null,
      "metadata": {},
      "amount_due": 0,
      "created_at": 1788174166,
      "amount_paid": 5000,
      "reference_id": "REF_YYYY"
    }
  },
  "created_at": 1788105600
}

Payload fields can expand over time. Ignore unknown fields and use the actual Test webhook received by your endpoint when generating typed models.

Handling guidance

Match the order ID to the order created and stored by your backend.
Verify amount, currency, amount paid, and remaining balance.
Use one atomic paid/fulfilled transition to prevent double fulfilment.
If status is inconsistent, retrieve the latest order/payment status before acting.