Consumer QR Payments

Customer-led QR payment

One interface for enabled QR payment paths

Payrallel provides one orchestration interface for consumer-scanned QR payments. It coordinates configured gateways, normalises transaction responses and exposes a consistent lifecycle for method discovery, QR creation, status verification and optional voiding.

Authentication and data format

Requests use JSON encoded as UTF-8. Each authenticated request requires an access token associated with one Payrallel Sales Channel, such as a kiosk, machine or payment entry point.

Authorization: {AUTHORIZATION_VALUE}
Content-Type: application/json; charset=UTF-8

Keep the access token on a trusted server. Never place it in browser code, public repositories, screenshots, logs or support transcripts.

1. Get supported QR payment methods

Retrieve the QR methods currently enabled for the sales channel.

GET {PAYRALLEL_API_BASE_URL}/api/payment-methods-list?type=consumer-scan-qr

Representative response

{
  "success": true,
  "methods": [
    { "name": "PayNow", "type": "consumer-scan-qr", "payrallelIdentifier": "paynow" },
    { "name": "Alipay+", "type": "consumer-scan-qr", "payrallelIdentifier": "alipayplus" }
  ]
}

Use the returned payrallelIdentifier as qrMethod when creating the QR payment.

2. Generate the QR payment

POST {PAYRALLEL_API_BASE_URL}/transactions/qr/consumerscan

{
  "amountInCents": 123,
  "qrMethod": "paynow",
  "customOrderId": "{TRANSACTION_REFERENCE}"
}

Representative response

{
  "success": true,
  "transactionId": "{TRANSACTION_REFERENCE}",
  "qrCode": "{QR_PAYLOAD}"
}

qrCode is the raw payment payload. Convert it into a QR image without modifying the value, even when the payload resembles a URL.

3. Query transaction status

Query with either your customOrderId or the returned transactionId.

POST {PAYRALLEL_API_BASE_URL}/transactions/actions/query

{ "customOrderId": "{TRANSACTION_REFERENCE}" }

// or

{ "transactionId": "{TRANSACTION_REFERENCE}" }

Representative response

{
  "success": true,
  "transaction": {
    "transactionId": "{TRANSACTION_REFERENCE}",
    "status": "processing",
    "paymentMethod": "paynow"
  }
}

Continue the approved polling or callback strategy until the transaction reaches a final state. Do not fulfil based only on a displayed QR, customer screen or redirect.

4. Void an approved transaction

When void is supported for the original gateway and transaction, identify the payment by customOrderId or transactionId.

POST {PAYRALLEL_API_BASE_URL}/transactions/actions/void

{ "customOrderId": "{TRANSACTION_REFERENCE}" }

Failed voids return success: false with a project-safe error description. Reconcile the original payment before retrying.

Transaction status values

Optional payment-success callback

A merchant callback URL can be configured in the Payrallel Merchant Administrator Portal. Successful payments can then produce a server-to-server notification containing transaction, gateway, payment-method, amount, currency, status and reference fields.

Signature verification procedure

1. Read the raw callback object.
2. Exclude the signature field.
3. Recursively sort object keys in ASCII/alphabetical order.
4. Serialise the sorted object deterministically.
5. Calculate HMAC-SHA256 using the Sales Channel access token as the secure key.
6. Compare using a timing-safe operation before accepting the notification.

expectedSignature = HMAC_SHA256(
  deterministicJson(sortedCallbackWithoutSignature),
  {SECURE_SALES_CHANNEL_ACCESS_TOKEN}
)

Treat the callback as untrusted until the signature is verified, then query and reconcile according to the project contract where required.

Implementation checklist

• Securely store the Sales Channel access token.
• Retrieve enabled methods instead of hard-coding availability.
• Generate unique, traceable customOrderId values.
• Convert the returned raw payload into a QR image without changing it.
• Handle processing, approved, declined and voided explicitly.
• Prevent duplicate fulfilment when polling and callback results overlap.
• Verify callback signatures before trusting notification data.
• Test expiry, timeout, retries, duplicate requests and reconciliation.