Node.js SDK
Use this package to create QR Pass sessions and read payment status from a Node.js server.
Install
npm install @scanandpay/nodeRequires Node.js 18 or later.
Credentials
Open Business Portal → Settings → Integrations and copy these four values into your server's environment.
To receive payment results, set your store's webhook address in the Business Portal under Settings → Integrations → Webhook address (must be a public https address). Scan & Pay sends payment confirmation webhooks to this address.
| Label | Environment variable |
|---|---|
| Merchant ID | SCANANDPAY_MERCHANT_ID |
| API Base URL | SCANANDPAY_API_BASE_URL |
| API Secret | SCANANDPAY_API_SECRET |
| Webhook Secret | SCANANDPAY_WEBHOOK_SECRET |
SCANANDPAY_MERCHANT_ID=your_merchant_id
SCANANDPAY_API_BASE_URL=https://api.scanandpay.com.au
SCANANDPAY_API_SECRET=your_api_secret
SCANANDPAY_WEBHOOK_SECRET=your_webhook_secretQuickstart — server
import express from 'express';
import { ScanAndPay, WebhookSignatureError } from '@scanandpay/node';
const app = express();
const client = new ScanAndPay({
merchantId: process.env.SCANANDPAY_MERCHANT_ID!,
apiBaseUrl: process.env.SCANANDPAY_API_BASE_URL!,
apiSecret: process.env.SCANANDPAY_API_SECRET!,
webhookSecret: process.env.SCANANDPAY_WEBHOOK_SECRET, // needed for webhooks
});
// 1. Create a session at checkout. The amount is in integer cents.
const session = await client.createSession({
amountCents: 1990, // $19.90
platformOrderId: 'order_456',
});
// 2. Read session status.
const status = await client.getStatus(session.sessionId);
// 3. Set your webhook address in the Business Portal (Settings → Integrations → Webhook address)
// and verify each incoming webhook with the SDK helper.
app.post(
'/webhooks/scanandpay',
express.raw({ type: 'application/json' }),
(req, res) => {
try {
const signature = req.header('x-scanpay-signature') ?? '';
const event = client.webhooks.verify(signature, req.body.toString('utf8'));
if (event.status === 'confirmed') {
// Mark the order paid using event.order_id and event.tx_id.
}
res.json({ received: true });
} catch (err) {
if (err instanceof WebhookSignatureError) {
res.status(401).send('Webhook verification failed');
return;
}
throw err;
}
},
);Quickstart — checkout component
The package includes CheckoutWidget, a React component that displays the QR Pass and updates the moment the payment completes or expires.
import { CheckoutWidget } from '@scanandpay/node/react';
function CheckoutPage({ session }) {
return (
<CheckoutWidget
session={session}
pollUrl="/api/scanandpay/status"
onSuccess={(sessionId) => { window.location.href = '/thank-you'; }}
theme="light"
/>
);
}Amount format
amountCents is always integer cents (e.g. 1990 for $19.90). Pass cents to the SDK as they are, and divide by 100 only when you display an amount.
await client.createSession({ amountCents: 1990, ... }); // $19.90
await client.createSession({ amountCents: 50, ... }); // $0.50
await client.createSession({ amountCents: 100000, ... }); // $1,000.00To display an amount, divide by 100:
const display = (session.amountCents / 100).toFixed(2); // "19.90"Error handling
Every error the SDK throws extends ScanAndPayError.
Production integration checklist
Use the SDK from your backend only. The browser can display the returned QR Pass or pay URL, but it must never receive your API Secret or Webhook Secret.
- Create your local order first. Store cart, customer, amount, currency, and a durable
platformOrderIdin your database with a pending payment status. - Create one Scan & Pay session for that order. Call
client.createSession()from your backend using the same order id. - Render the payment step as pending. Show the returned session with
CheckoutWidget, your own QR Pass renderer, or a redirect to the returned pay URL. Do not send the customer to a success page yet. - Expose a small status endpoint. Point
pollUrlat your backend. It should callclient.getStatus(sessionId)and return only the public status fields your UI needs. - Set your webhook address and verify webhooks. Set your public
httpswebhook address in the Business Portal under Settings → Integrations → Webhook address. Verify incoming webhooks on raw request bytes usingclient.webhooks.verify(signature, rawBody)before trusting the payload. - Fulfil from a confirmed payment. A verified webhook with
event.status === 'confirmed'is your signal to fulfil. If a webhook does not arrive, confirm withclient.getStatus(sessionId). - Protect your credentials. Never place them in source code repositories, browser code, mobile apps, logs, screenshots or support tickets.
Integration pitfalls
Three mistakes to avoid in a first integration:
- Create the order before the session. The session is tied to your
platformOrderId, and the webhook refers back to it. Save the order aspendingfirst, then callclient.createSession({...}). - Do not complete the order when the customer clicks Place Order. Treat Scan & Pay as a method that confirms later: the customer must scan the QR Pass and confirm the payment in Scan & Pay first.
- Only a confirmed payment means money has moved. Mark the order paid when a verified webhook arrives with
event.status === 'confirmed', or when the status check returnsPAID.