A digital license store has two separate jobs: collect payment and deliver the correct unused key. Trust Gateway can create a hosted UPI checkout and report a verified payment status; your store remains responsible for its inventory, customer account and delivery decision. Joining those jobs through a durable purchase record prevents a page refresh or delayed notification from issuing the wrong key.
- Reserve the selected product and calculate its price on your server.
- Create one gateway order and save its ID with the purchase.
- Send the customer to hosted checkout.
- Verify paid status on your server.
- Assign and reveal one available license exactly once.
Model the purchase before taking payment
Create a local purchase ID linked to the customer account, product variant, quoted amount and a state such as awaiting payment. Decide how long inventory is reserved and what happens if all keys sell out. A message saying “two keys available” should reflect your own stock records; Trust Gateway does not manage or replenish the license pool for you.
Use the server's trusted product catalog to calculate the amount. A buyer can edit a browser form, so never let a submitted price or product label be the final authority. If a referral discount is supported, validate it on the server and store the applied discount alongside the original quote. Then create the gateway order with your server-side API key and store its order ID and returned exact payable amount. Read the API order guide for the current field contract.
Keep the gateway key out of the storefront
The browser only needs the hosted checkout URL and the status of its own purchase. It must never receive the Trust Gateway API key. If your store shows “API key is not configured on the server,” inspect the store process's private environment setting and whether that process was restarted after the setting changed. This is a configuration error in the calling application; adding a webhook does not supply a missing authentication key.
Keep a single configuration name across web processes and background workers, and avoid logging its value. Test a harmless authenticated request after deployment. Do not put a real key in a mobile app bundle, screenshot, support chat or repository. The key-storage guide covers rotation and troubleshooting.
Confirm the saved order, not the browser story
After checkout, the buyer may return to your site, close their browser or send you a payment screenshot. None of those events alone grants a license. Your backend should query GET /api/v1/orders/status/:order_id with its API key and require paid: true. Compare the returned gateway order ID and amount with your purchase record before changing its state. If status is pending or uncertain, show a waiting or support state rather than claiming success.
The verification can work without a webhook. A webhook, when configured, can prompt your server to check sooner, but the authenticated status route remains a useful fallback. For a complete no-webhook sequence, see the status API guide. A payment notification delay should not make the customer buy a second key by accident.
Assign one key atomically
Fulfilment is your store's database operation. In one transaction, confirm that the purchase is not already fulfilled, select an available key for the purchased product, mark that key assigned to this purchase, and mark the purchase delivered. Enforce uniqueness for the gateway order ID and for the license assignment. If two workers process the same successful payment together, exactly one should win; the other should return the existing assignment.
Do not email or display a license before the transaction commits. If the stock is unexpectedly empty after payment, keep the purchase paid but undelivered and route it to support. That case needs a fulfilment remedy, not a fabricated “payment failed” status. Keep a clear audit record of which product and key assignment belongs to each gateway order, while protecting the key itself from unnecessary logs.
Make recovery understandable to customers
A signed-in customer should be able to revisit purchase history and see whether a purchase is awaiting payment, awaiting verification, delivered or needing support. Reloading that page must not create another order or assign another license. Show the gateway reference for support without exposing API credentials. If a link expires, check the original order's outcome before offering a new attempt.
Finally, run a controlled small purchase and test a delayed confirmation, duplicate status checks, sold-out stock and interrupted browser return. These cases reveal delivery bugs that a visually successful checkout cannot. Use the checkout test matrix to record your result.