Integrating dynamic QR payments: a developer's guide
Short answer: A dynamic QR integration has four parts: create a payment request with the amount and your order reference, show the returned QR or link, receive a signed webhook when it's paid, and fulfil the order idempotently. Add a status check as a fallback and reconcile daily.
The flow
- Create. Your server calls the provider's API with the amount, your order reference and an expiry. Never create payment requests from the browser with your secret key.
- Display. Show the returned QR on desktop. On mobile, show the QR plus a link to the hosted pay page, since customers can't easily scan their own screen.
- Confirm. The provider sends a webhook to your server when the customer pays.
- Fulfil. Mark the order paid and deliver. Then tell the browser, by polling your own backend or a websocket.
Webhooks done properly
- Verify signatures. Treat any unsigned or wrongly signed request as fake. Qrix signs every delivery, and replacing your webhook URL issues a new signing secret, so update your config at the same time.
- Respond fast, work later. Return a 2xx quickly and process in a background job.
- Expect retries. If your server is down, deliveries are retried. Qrix retries for about fifteen hours, so the same event can arrive more than once.
- Be idempotent. Key fulfilment on the payment or order ID so a repeated webhook never ships twice.
Choosing expiry
Checkout QR codes usually expire in minutes. Invoices and payment links can stay payable for days. After expiry the code stops being shown and the link reports it's no longer payable. If a customer comes back late, create a new request rather than extending an old one.
Status checks as a fallback
Webhooks can be delayed by your own infrastructure. Before cancelling an unpaid order, call the transaction inquiry endpoint to confirm its final status.
Test vs live
Keep separate keys and webhook URLs per environment, label keys by the server that uses them, and revoke unused keys. In the Qrix portal, the environment switch makes clear which mode you're in: in live, every payment is real money.
Reconciliation
Each day, match your paid orders against the provider's transaction export and settlement report. With dynamic QR, the order reference makes this a join rather than a hunt. Investigate anything paid but not fulfilled, and anything fulfilled but not paid.
Go-live checklist
- Secret keys only on the server, never in client code
- Webhook signature verification on
- Idempotent fulfilment
- Mobile flow shows a pay link, not just a QR
- Status check before cancelling unpaid orders
- Daily reconciliation job
Building with Qrix
Qrix gives you a REST API with live and test environments, signed webhooks, a transaction inquiry API, refunds and payouts on the same integration. Merchants typically go live within hours of signing.
Frequently asked questions
How do I know a dynamic QR payment is real?
Rely on a signed webhook or a server-side status check from your provider, never on a message from the browser or a screenshot.
What happens if my webhook endpoint is down?
Providers retry delivery. Qrix retries for about fifteen hours, so make fulfilment idempotent.
Should the QR be shown on mobile?
Show the QR and a link to the hosted pay page, because customers can't easily scan a code on the same phone.
Can I use the same API for payouts?
With Qrix, pay-ins and payouts run through a single Settlix API.