PHP SDK
Use this package to create QR Pass sessions and read payment status from a PHP application.
Install
composer require scanandpay/phpRequires PHP 8.1 or later with the curl, json and hash extensions.
Credentials
Open Business Portal → Settings → Integrations and copy your Merchant ID, API Secret, and Webhook Secret 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.
Quickstart
use ScanAndPay\ScanAndPay;
use ScanAndPay\Exceptions\WebhookSignatureException;
$client = new ScanAndPay(
merchantId: getenv('SCANANDPAY_MERCHANT_ID'),
apiSecret: getenv('SCANANDPAY_API_SECRET'),
webhookSecret: getenv('SCANANDPAY_WEBHOOK_SECRET'), // needed for webhooks
baseUrl: getenv('SCANANDPAY_API_BASE_URL') ?: 'https://api.scanandpay.com.au',
);
// 1. Create a session at checkout. The amount is in integer cents.
$session = $client->createSession(
amountCents: 1990, // $19.90
platformOrderId: 'order_456',
);
// 2. Display the QR Pass on the page.
echo scanandpay_checkout($session, pollUrl: '/scanandpay/status');
// 3. Read session status.
$status = $client->getStatus($session->sessionId);
// 4. Set your webhook address in the Business Portal (Settings → Integrations → Webhook address)
// and verify each incoming webhook with the SDK helper.
try {
$event = $client->webhooks()->verify(
signature: $_SERVER['HTTP_X_SCANPAY_SIGNATURE'] ?? '',
body: file_get_contents('php://input'),
);
if ($event->isPaid()) {
// Mark the order paid using $event->orderId and $event->txId.
}
} catch (WebhookSignatureException $e) {
http_response_code(401);
exit('Invalid webhook');
}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.
$client->createSession(amountCents: 1990, ...); // $19.90
$client->createSession(amountCents: 50, ...); // $0.50
$client->createSession(amountCents: 100000, ...); // $1,000.00To display an amount, divide by 100:
$display = number_format($session->amountCents / 100, 2); // "19.90"Error handling
Every error the SDK throws extends ScanAndPay\\Exceptions\\ScanAndPayException.
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
scanandpay_checkout(), 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 fetch status with the SDK 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 using$client->webhooks()->verify($signature, $rawBody)before trusting the payload. - Fulfil from a confirmed payment. A verified webhook where
$event->isPaid()is true is your signal to fulfil. If a webhook does not arrive, confirm the status with the SDK. - 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 call$client->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 where
$event->isPaid()is true (the raw payload says"status": "confirmed"), or when the status check returnsPAID.