QR Payments
Accept QR-based payments in-store, on a counter, on a poster, or anywhere else a printed or displayed code makes sense.
QR Payments is the most common Scan to Pay acceptance pattern. Your backend creates a code, you display it as a QR (printed, on a screen, or on a POS terminal), and the customer scans it from the Scan to Pay app on their phone to authorise the payment.
This section covers everything QR-related: when to use static vs dynamic codes, how to create and manage them, how to render them, the code lifecycle, and the business rules that govern them.
Other QR-driven flows live elsewhere. For e-commerce checkouts that render a QR on a web page, see Bluebox hosted checkout. For QR codes on invoices and statements, see Bill payment. For your own mobile app launching the Scan to Pay app on the same device, see App-to-app.
When to use which QR pattern
Pick the pattern that matches how the QR will be presented to the customer.
| Pattern | When to use | Page |
|---|---|---|
| Static QR | One QR per merchant or per terminal, printed once. Customer enters the amount on their phone, or you update the amount on the same code before each purchase. | Static QR |
| Dynamic QR | One fresh QR per transaction, with the amount embedded. Typical for POS terminals, kiosks, and digital signage. | Dynamic QR |
Both use the same POST /code/create endpoint — the difference is whether useOnce is true and whether you reuse the code across transactions.
How a QR payment works
The flow is the same for every QR pattern:
- Your backend creates a payment code via
POST /code/create. The platform returns a 10-digit code. - You present the code as a QR — either render it yourself or use the Rendering the QR endpoint to fetch a styled PNG.
- The customer scans the QR from the Scan to Pay app and authorises the payment.
- Scan to Pay notifies your backend via webhook with the outcome.
Step 1 differs slightly between static and dynamic patterns — see the per-pattern pages for the exact request bodies.
In this section
- Static QR — one printed code per merchant or terminal.
- Dynamic QR — fresh code per transaction.
- Rendering the QR — the styled-PNG endpoint, colour codes, and how to embed.
- Managing QR codes — update amount, block, unblock, edit, delete, query.
- QR code lifecycle — the five states a code can be in.
- QR Code Payments — business rules — the constraints you need to know.
What's next
- Try it end to end → Quickstart
- Receive the payment notification → Webhooks
- Understand transaction outcomes → Transaction states
- Handle tips at checkout → Handling tips
- Refund or reverse a QR transaction → Refunds and reversals
Updated 4 days ago