Bulk QR codes

The bulk QR endpoint generates a large batch of QR codes in a single call. It's designed for PSPs distributing pre-printed QR codes to their merchants — for example, table-tents at a chain of cafés, or sticker rolls for taxi drivers.

For single-QR creation, see Managing QR codes.

Endpoint

Acquirers and merchants get 401 Unauthorized from this endpoint — it's PSP-exclusive.

How the flow works

Bulk QR generation is asynchronous — the platform queues the work, generates the codes in the background, and reports completion. There are two ways to learn about completion:

1. Synchronous response — for small batches, the response returns once the batch is generated, with the full list of codes inline
2. Asynchronous callback — supply a callbackUrl and the platform POSTs the completed batch to your endpoint when ready

The threshold between sync and async depends on the batch size — typically a few hundred codes is the cutoff. The platform decides; you don't.

Request

curl -X POST https://qa.scantopay.io/portal/restful/bulkQr \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "qrCount": 500,
    "callbackUrl": "https://psp.example/webhooks/bulk-qr-ready"
  }'

Request fields:

Synchronous response

For small batches, the response includes the full list of codes inline:

{
  "bulkQrRequestId": "BULK-9F3A7C1D",
  "qrCount": 500,
  "pspId": 42,
  "qrCodes": [
    { "code": "8656849931", "merchantReference": "BULK-9F3A7C1D-0001" },
    { "code": "6400594798", "merchantReference": "BULK-9F3A7C1D-0002" },
    ...
  ]
}

Response fields:

Asynchronous response

For larger batches, the immediate response confirms the request was accepted:

{
  "bulkQrRequestId": "BULK-9F3A7C1D",
  "qrCount": 10000,
  "pspId": 42
}

(qrCodes is absent — they'll arrive at your callback URL when ready.)

When generation completes, the platform POSTs to your callbackUrl with the full payload:

POST https://psp.example/webhooks/bulk-qr-ready
Content-Type: application/json

{
  "bulkQrRequestId": "BULK-9F3A7C1D",
  "qrCount": 10000,
  "pspId": 42,
  "qrCodes": [
    { "code": "8656849931", "merchantReference": "BULK-9F3A7C1D-00001" },
    ...
  ]
}

Your callback handler should respond 200 OK quickly — the platform doesn't retry indefinitely if the callback fails.

Common errors

What you do with the codes

Each code in the response is a fully-formed 10-digit Scan to Pay QR value, ready to be:

• Rendered as a QR image — via the public QR rendering endpoint (/public/qr/{code}), see Rendering QR codes
• Printed on physical media — table tents, stickers, signage
• Embedded in a digital surface — email confirmations, app screens

The codes are assigned to your PSP but not bound to a specific merchant or amount at generation time. They become payable once you attach them to a merchant via the standard /code flow — see Managing QR codes.

Reconciling the batch

Each generated code has an auto-assigned merchantReference of the form BULK-<requestId>-<index>. Combined with the bulkQrRequestId, this gives you everything you need to:

• Track which batch a printed QR came from
• Identify duplicate prints (same merchantReference)
• Audit-trail back to the original API request

Store the bulkQrRequestId alongside your distribution records — it's the most useful single field for support tickets about a specific batch.

What's next

• Render a code as a QR image → Rendering QR codes
• Assign a code to a merchant and amount → Managing QR codes
• QR lifecycle rules → QR payments — business rules
• Cross-cutting rules → Business rules