A webhook is useful when your application can receive an HTTPS notification, but it is not required to create a Trust Gateway order or read its status. A small website, bot or license store can keep its API key on the server, send the customer to hosted checkout and check the same gateway order later. The important part is to make the status check a server-side decision, not a browser claim that the customer paid.
- Your server creates the order with its API key.
- Save the returned order ID and exact payable amount.
- The customer opens the hosted checkout and approves a UPI request.
- Your server queries that order's status before delivering anything.
Start with a private integration key
Connect a supported receiving account and confirm that the merchant can create orders. Store the Trust Gateway API key in your server's private environment configuration. Send it in the X-API-Key header from the server; never place it in JavaScript downloaded by customers, a checkout URL or a mobile app bundle. A page saying that the key is not configured usually points to the calling application's server configuration, not a missing webhook.
Make the purchase amount on your server from your product record. A browser-submitted price can be changed by the customer. Call POST /api/v1/orders/create with that amount, and handle non-success HTTP responses. The developer documentation contains the current request and response examples. The create response includes an order_id, checkout_url, requested amount and actual payable amount.
Save the order before redirecting
Write a local purchase record that joins your user, product and business order to the returned gateway order_id. Save the exact returned amount as the expected payment total. For the FamPay route, the payable amount may differ slightly from the requested amount when the service needs to distinguish concurrent payments. Your confirmation check must use the returned payable value.
Only after that record is safely saved should you redirect the customer to the returned hosted checkout path on https://trustgateway.in. If the browser closes or your server restarts, the saved gateway ID lets you resume verification. Do not create a second payment order just because the customer refreshed a return page.
Check status from your backend
Call GET /api/v1/orders/status/:order_id with the same server-side API key. A normal unpaid response reports status: pending and paid: false. A verified successful response reports paid: true; an authorized caller also receives payment details including the gateway order ID and amount. Match both to your saved purchase before granting access. An unknown order ID returns an error; an expired order should not be presented as paid.
Public checkout polling may show a simple success indicator, but it does not replace the authenticated data your business needs. Treat a redirect to your return URL, a QR scan, a screenshot, or a user-entered UTR as information to investigate, not proof to deliver a product. The payment status lifecycle explains pending, expiry and confirmation states in more detail.
Poll within a sensible window
Your return page can ask your own backend for the purchase state. The backend can check the gateway at a modest interval while the customer is waiting, then slow down or stop after the order reaches a terminal state. Respect HTTP 429 responses with backoff; rapidly repeating a failed check will not make a payment settle sooner. If a request times out, check the same saved order again rather than issuing a new one.
The current checkout has a ten-minute payment window. FamPay verification can briefly continue after that window to account for an on-time payment notification arriving late. Do not declare a customer unpaid solely because their browser countdown reached zero. Ask the gateway for the actual order state and preserve uncertain attempts for review.
Deliver once, even if the status is checked repeatedly
Two browser tabs or background jobs may observe paid: true at nearly the same time. Make product delivery an atomic state change in your own database: only the first transition from unpaid to fulfilled may issue a license, credit or download. Later checks should show the already-delivered result. Keep the gateway order ID unique in that fulfilment record.
Webhooks can still be added later as a faster notification path. Continue using the authenticated status API as a recovery check when a notification is delayed or missed. For a complete integration, follow the first API order checklist and test one controlled payment before accepting customer purchases.