Best practices

A short checklist that keeps QRPay integrations secure and predictable. Everything here follows from how the API actually behaves — token expiry, the return-URL redirect and the response envelope.

Keys and environments

• Keep your keys server-side only. The client_id and secret_id must never appear in browser code, mobile apps or public repositories. Every call to QRPay should originate from your backend over HTTPS.
• Stay in SANDBOX until launch. Keys created in the merchant panel start in SANDBOX mode, so no real money moves while you build. Switch the key to PRODUCTION only once your return-URL verification and error handling are in place.

Access tokens

• Request a fresh access token per checkout session. Tokens expire after 600 seconds (expire_time in the token response). Fetching one at the start of each payment flow is simpler and safer than caching a token that may die mid-checkout.

Orders and verification

• Store the payment token before you redirect. When /payment/create responds, save data.token against your order first, then send the customer to payment_url. That stored token is the only reliable way to match the redirect back to the right order.
• Verify on the return_url, server-side. Treat a payment as paid only when the token delivered to your return_url matches an order you created — see Verify payment. Never mark an order paid from client-side state, and never trust an amount or currency echoed back by the browser — re-check against what you stored when creating the payment.
• Make fulfilment idempotent. Customers refresh, and redirects can arrive more than once. If the token is already marked paid, acknowledge the request and do nothing — never fulfil the same order twice.

Requests and diagnostics

• Send amounts as strings with two decimal places. "100.00", not 100 — a numeric value is rejected with 400 · The amount must be a string.
• Use HTTPS for your return_url and cancel_url. The payment token travels on that redirect; plain HTTP exposes it in transit.
• Log the full response envelope. message.code, the success/error array and type together identify every outcome (see Response codes). They are also the first thing support will ask for.
• Handle errors deliberately, and keep the integration current. Map the documented codes to your own retry and user-messaging logic as described in Error handling, and review these docs when you upgrade your QRPay installation.