Node.js SDK

Use this package to create QR Pass sessions and read payment status from a Node.js server.

Install

Terminal
bash
npm install @scanandpay/node

Requires 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.

LabelEnvironment variable
Merchant IDSCANANDPAY_MERCHANT_ID
API Base URLSCANANDPAY_API_BASE_URL
API SecretSCANANDPAY_API_SECRET
Webhook SecretSCANANDPAY_WEBHOOK_SECRET
.env
bash
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_secret

Quickstart — server

server.ts
ts
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.

CheckoutPage.tsx
tsx
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.00

To 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.

  1. Create your local order first. Store cart, customer, amount, currency, and a durable platformOrderId in your database with a pending payment status.
  2. Create one Scan & Pay session for that order. Call client.createSession() from your backend using the same order id.
  3. 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.
  4. Expose a small status endpoint. Point pollUrl at your backend. It should call client.getStatus(sessionId) and return only the public status fields your UI needs.
  5. Set your webhook address and verify webhooks. Set your public https webhook address in the Business Portal under Settings → Integrations → Webhook address. Verify incoming webhooks on raw request bytes using client.webhooks.verify(signature, rawBody) before trusting the payload.
  6. Fulfil from a confirmed payment. A verified webhook with event.status === 'confirmed' is your signal to fulfil. If a webhook does not arrive, confirm with client.getStatus(sessionId).
  7. 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:

  1. Create the order before the session. The session is tied to your platformOrderId, and the webhook refers back to it. Save the order as pending first, then call client.createSession({...}).
  2. 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.
  3. 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 returns PAID.

Resources