API Reference

Payments API

Create a QR Pass session at checkout, display the QR Pass on screen, and read the payment status.

POST /createPaymentSession #

Creates a payment session and returns its QR Pass, payment link, session reference, and status.

Your Business Portal profile needs a business name. Without one, creating a session returns 400 with "Complete your Business Portal profile before taking payments."

Sending the same platformOrderId again returns the existing session rather than creating a new one. This also applies after a session expires: returning the expired session. An expired session needs a new order reference (for example, with a retry suffix).

Request fields

FieldTypeReq.Description
platformOrderIdstringyesYour unique order reference. Sessions are unique per reference.
amountCentsintegeryesTotal in cents (e.g. 1990 for $19.90).
metadataobjectnoOptional. Up to 50 string key-value pairs (each key and value at most 500 characters). Returned in every response and webhook for the session.

Example request

curl
bash
curl https://api.scanandpay.com.au/createPaymentSession \
  -X POST \
  -H "X-Scanpay-Key: $SCANANDPAY_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformOrderId": "order_456",
    "amountCents": 1990,
    "metadata": { "cart": "c_789" }
  }'

Response

The response returns the session reference (reference: Optional. The server generates the reference returned in the response; use platformOrderId to match your own orders.), the payment link (payUrl), the QR image (qrUrl), and the current session status.

200 OK
json
{
  "success": true,
  "sessionId": "SP_SESS_abc123def456",
  "payUrl": "https://pay.scanandpay.com.au/p/SP_SESS_abc123def456",
  "qrUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "payId": null,
  "amountCents": 1990,
  "currency": "AUD",
  "reference": "W_abc123def456gh78",
  "status": "WAITING",
  "expiresAt": "2026-04-30T12:35:00.000Z",
  "metadata": { "cart": "c_789" }
}

A payment session expires five minutes after creation, and the expiresAt field carries the exact moment. Once expired, its status is EXPIRED and it cannot be paid, so create the session only when the shopper is ready to pay (not when the cart is built), and create a new one if the shopper comes back later.

Display the QR Pass #

Show the amount (amountCents) and render the QR image (qrUrl) on screen:

HTML
html
<div class="checkout">
  <p>Amount: $19.90</p>
  <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." alt="Scan to pay" />
</div>

Where scanning is not possible — such as when the shopper is browsing on the same mobile device — offer the payment link (payUrl) so they can tap to open the payment page directly.

GET /getPaymentStatus #

Returns the current state of a payment session using its sessionId. Payment results are delivered to the webhook address configured in the Business Portal under Settings → Integrations → Webhook address (see webhooks), which you verify using the SDK helper.

curl
bash
curl "https://api.scanandpay.com.au/getPaymentStatus?sessionId=SP_SESS_abc123def456" \
  -H "X-Scanpay-Key: $SCANANDPAY_API_SECRET"

Response

200 OK
json
{
  "success": true,
  "sessionId": "SP_SESS_abc123def456",
  "status": "PAID",
  "amountCents": 1990,
  "currency": "AUD",
  "payId": null,
  "reference": "W_abc123def456gh78",
  "createdAt": "2026-04-30T12:30:00.000Z",
  "paidAt": "2026-04-30T12:32:14.000Z",
  "expiresAt": "2026-04-30T12:35:00.000Z"
}

Payment statuses

  • pending (WAITING): The customer has not paid yet. Continue polling.
  • paid (PAID): Payment is confirmed. Mark an order paid only when the status is paid.
  • failed (FAILED): The bank declined the payment, or the session was cancelled.
  • expired (EXPIRED): The 5-minute payment window ended without a payment.

Any unsuccessful response means the payment is not paid.