Trust Gateway gives a merchant one place to create a UPI payment request and follow its outcome. The customer pays in a UPI app; your business needs a separate, verified order status before it delivers anything. This guide follows that entire path, including the points where a payment can remain uncertain.
- Connect a receiving merchant account and activate the plan required for API access.
- Create a payment link in the dashboard or an order through the API.
- Let the customer check the payee and amount in their UPI app.
- Confirm the order on your server through status lookup or a webhook before fulfilment.
What Trust Gateway does
Trust Gateway is a UPI-first checkout and order-tracking workspace. It can create an order-specific QR code, present a hosted payment page, produce a shareable link, and expose the resulting order status to an application. Supported merchant connections include FamPay, BharatPe and Paytm, but each connection has its own setup and verification path. Check the options actually available in your dashboard before promising a payment method to customers.
The gateway's order record is not the same as your receiving account's financial record. The first describes the request and its status; the second shows money received. When they disagree, pause fulfilment and investigate. A QR being generated, scanned, saved or opened never proves that a payment settled.
1. Set up the receiving account
Create an account, review the current subscription terms, and finish merchant connection in the dashboard. Check the UPI ID and receiver name by opening a small test request in a separate UPI app. If the receiver differs from the account you expected, stop there and correct the connection. Changing a merchant connection while customers have open links can make reconciliation harder, so keep a record of the change and retest.
For API orders, generate the merchant API key in your account and keep it on your server. The current order-creation route requires an active merchant subscription, a valid API key, a configured receiving UPI ID and a positive amount. A browser app must call your own backend, which can then call Trust Gateway; embedding the key in browser JavaScript or a customer-facing URL exposes it.
Confirm the receiving identity, run one small end-to-end request, compare the gateway status with the receiving account, and document who handles mismatches.
2. Create a payment request
There are two useful starting points. A payment link suits an invoice, chat sale or manual order: create it in the dashboard, review the amount and checkout, then share its HTTPS URL. An API order suits a website, bot or app that already has its own order record. In both cases, keep a reference in your own system so a customer question can be traced to the same gateway request.
The current compatibility API accepts GET or POST at /qr.php. Here is a server-side request using the header form of the API key:
curl -G 'https://trustgateway.in/qr.php' \
-H 'X-API-Key: YOUR_API_KEY' \
--data-urlencode 'amount=499'A successful response contains data.order_id, data.qr_url, the receiving data.upi_id, amount and expiry timestamps. Store the returned order ID next to your own cart or invoice ID. The QR URL is a display asset; it is not a receipt. The documented API quickstart gives the concise version of this flow.
3. Show the checkout clearly
Present the exact payable amount, a readable QR, receiver identity, order reference and current status. On desktop, customers generally scan the code with another device. On mobile, a supported UPI app handoff can reduce friction, but the customer still needs to review and approve the transaction in that app. Do not mark the page as successful just because the app opened or the user returned to the browser.
Trust Gateway creates an order with a limited validity window. The current /qr.php order route sets a ten-minute expiry. Display the deadline honestly, and avoid encouraging a second attempt while the first one is uncertain. If the customer says they paid near expiry, compare the receiving account's transaction with the gateway order before making a fresh request.
4. Confirm the order, not the browser redirect
Payment verification depends on the merchant connection. Trust Gateway checks the available payment signal for that source and updates the order when it can match a transaction. Do not assume every source confirms at the same speed or carries the same identifiers. An unmatched or ambiguous event should remain pending for review rather than become a false success.
Your server can check a known order through /verify.php with the merchant API key and returned order ID:
curl -G 'https://trustgateway.in/verify.php' \
-H 'X-API-Key: YOUR_API_KEY' \
--data-urlencode 'order_id=ORDER_ID'The success response reports paid: true and the matched order data. Before fulfilment, compare its order ID and amount with your own stored order. A pending response can use paid: false and an error status while verification is still in progress; that is not a licence to create a replacement charge immediately. A failed or expired order also needs separate handling. Read the status endpoint notes for the current response contract.
5. Use a webhook without trusting it blindly
A configured webhook URL lets the gateway send a payment.success event to your server when an order is confirmed. The current payload includes order ID, amount, status, transaction details and a signature; the request also carries X-Gateway-Signature. Your endpoint should compare the signature using your configured secret, confirm the expected order and amount, and process the same order only once.
The current webhook signature is an HMAC-SHA256 digest over four fields joined with a pipe: order_id|amount_to_two_decimals|status|utr_or_NONE. Use the configured webhook secret for that merchant; if no separate secret exists, the gateway uses its API key. Compare the received signature in constant time and reject events that do not match. Keep this check on the server and protect the secret like an API credential.
Verify the signature, look up the order in your own database, compare its expected amount, then mark it fulfilled only if it has not been fulfilled already. If any part is uncertain, leave the order for status lookup or manual review.
Webhook delivery is a notification path, not a reason to delete your status check. Networks can fail and callbacks can be delayed. If a callback is missing, query the authenticated order endpoint. If the same event is delivered twice, an idempotent fulfilment record prevents two downloads, credits or shipments. Never let an unauthenticated browser request claim that an order has been paid.
Understand pending, paid and expired
| State | What it means | Merchant action |
|---|---|---|
| Pending | A request exists, but confirmed payment is not available yet. | Keep checkout open; check status and receiving account before retrying. |
| Paid | The gateway has a verified successful order. | Match order ID and amount; fulfil once. |
| Expired or failed | The request can no longer be treated as an active checkout. | Investigate any claimed late payment before issuing another link. |
An expired checkout and an actual bank transfer are different facts. If the customer completed UPI approval just as the page expired, use the order reference, approximate time and receiving-account record to investigate. Do not ask for their UPI PIN, bank password or screen-sharing access.
Common issues and the next check
“I paid, but the page still says pending”
Check the gateway order status and your receiving-account transaction history. Compare amount, time and available transaction reference. A screenshot can start a support investigation, but it should not be your sole evidence for automatic fulfilment. If the receiving account has no matching credit, tell the customer the payment is still being checked.
“The API rejected my request”
Confirm the plan is active, the API key belongs to the merchant account, a receiving UPI ID is configured and the amount is positive. Keep the complete server-side error code in your own logs without recording the API key. A SUBSCRIPTION_REQUIRED response means the account needs an active eligible plan.
“The customer paid twice”
Keep both transaction references and both gateway order IDs, even if only one order was meant to be fulfilled. Do not merge the payments based solely on equal amounts. Reconcile the receiving account first, then handle the extra payment through your normal support and refund process.
“My webhook did not arrive”
Check that the configured callback is a public HTTPS endpoint, returns a successful HTTP response and can handle repeat events. Query the status API for the specific order before changing customer access. Treat a webhook as an acceleration path, not as the only source of truth.
A practical launch checklist
- Open the merchant account and confirm which receiving source is active.
- Check the payee shown in a real UPI app on a low-value test.
- Record your own order ID and the Trust Gateway order ID together.
- Test a successful payment, an abandoned checkout and an expired request.
- Test a delayed status update and a repeated webhook event.
- Make sure fulfilment happens only after a confirmed, matching order.
- Give support staff a way to find both the checkout record and the receiving-account transaction.
Keep these checks small and repeat them when you change API credentials, merchant connections or checkout code. The goal is a payment flow whose outcome your team can explain to a customer, not a page that merely looks successful.
Where to go next
If you are connecting a website or bot, use the Trust Gateway API documentation for request syntax and the architecture overview for the lifecycle. If you collect manually, start with the payment-link guide. For support cases, the order-status guide explains how to keep pending and paid distinct.