Managing QR codes

Once a code exists, the Codes API exposes seven operations to inspect or modify it. This page covers each operation, when to use it, and the request shape.

All operations require EXTERNAL role authentication — your merchant or PSP credentials. See Authentication.

Quick reference

The code path parameter is the 10-digit code returned from Create.

Query

Inspect an existing code — useful for reconciliation, debugging, and verifying state before showing a QR.

curl -X GET "https://qa.scantopay.io/pluto/code/0123456789" \
  -u "$USERNAME:$PASSWORD"

Returns the full code record: state, amount, merchantReference, expiry, sub-merchant info, basket items (if any), and any active locks. See QR code lifecycle for what the codeState values mean.

Edit

Update one or more of the editable non-amount fields on a code:

curl -X PUT "https://qa.scantopay.io/pluto/code/0123456789" \
  -u "$USERNAME:$PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "shortDescription": "Acme Coffee — special promo",
    "merchantReference": "static-counter-01-promo"
  }'

You can also extend the expiry, change the sub-merchant name, or update terminal/MCC overrides. You cannot change useOnce or reserveQR after creation.

Update amount

The most common management operation. Reset a re-usable code (useOnce: false) to a new fixed amount for the next transaction.

curl -X PUT "https://qa.scantopay.io/pluto/code/0123456789/amount" \
  -u "$USERNAME:$PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 245.00,
    "merchantReference": "static-counter-01-sale-2025-05-14-038"
  }'

Use this for Static QR variant B where you control the amount from your backend.

⚠️

merchantReference on update-amount must be unique per call. It becomes the per-transaction reference, not the per-code reference. The platform enforces uniqueness — sending the same reference twice will error.

Block and unblock

Block a code to temporarily prevent payments without deleting it. The code is preserved but moves to the Blocked state — scans fail until you unblock.

# Block
curl -X PUT "https://qa.scantopay.io/pluto/code/0123456789/block" \
  -u "$USERNAME:$PASSWORD"

# Unblock
curl -X PUT "https://qa.scantopay.io/pluto/code/0123456789/unblock" \
  -u "$USERNAME:$PASSWORD"

Typical use cases:

• End of trading day — block all your static codes overnight to prevent off-hours payments
• Investigating a dispute — block a code while you reconcile, then unblock once cleared
• Suspected fraud — block a code that's seen suspicious scan activity

For permanent removal, use Delete below instead.

Delete

Permanently remove a code. The code's codeState becomes Deleted and cannot be paid against — even if you've still got the QR printed somewhere, scans will fail.

curl -X DELETE "https://qa.scantopay.io/pluto/code/0123456789" \
  -u "$USERNAME:$PASSWORD"

📘

Delete is not "reuse the same code value." Once deleted, the same 10-digit code value cannot be recreated. Create a new code if you need acceptance to continue.

State transitions

These operations move the code between states. The full state machine is on QR code lifecycle:

        ┌──────────────┐
        │              │
   ┌────► Available ───┼─── block ────► Blocked
   │    │              │                  │
   │    │              ◄─── unblock ──────┘
   │    └─┬────────────┘
   │      │
   │      ├─ scan ──► Locked ──► successful payment ──► Used (terminal)
   │      │              │
   │      │              └─ failed/timeout ──► Available
   │      │
   │      └─ delete ──► Deleted (terminal)
   │
   └─ update amount, edit  (state preserved)

Error handling

The Codes API returns standard error codes — see Errors. The most common code-management failures:

What's next

• The full state machine → QR code lifecycle
• Reuse a code for the next sale → Static QR variant B
• Refund or reverse a completed transaction → Refunds and reversals
• Auto-rendered API reference → Codes API