Move money with
one clear contract.

import crypto from "node:crypto";

const apiBase = "https://api.spqr-payments.com";
const apiKey = process.env.SPQR_API_KEY;
const apiClientSecret = Buffer.from(process.env.SPQR_API_CLIENT_SECRET, "hex");
const merchantSecret = Buffer.from(process.env.SPQR_MERCHANT_SECRET, "hex");

const body = JSON.stringify({
  merchant: "acme_my",
  amount: 12500,
  currency: "MYR",
  external_id: "order-8402",
  country: "MY",
  payment_method: "duitnowqr",
  return_url: "https://shop.example.com/orders/order-8402",
  callback_url: "https://api.shop.example.com/webhooks/spqr",
  payer: { customer_uid: "customer-184" }
});

const timestamp = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const idempotencyKey = crypto.randomUUID();
const canonical = `POST\n/payments\n${bodyHash}\n${timestamp}\n${idempotencyKey}\n`;
const inner = crypto.createHmac("sha256", merchantSecret).update(canonical).digest();
const signature = crypto.createHmac("sha256", apiClientSecret).update(inner).digest("hex");

const response = await fetch(`${apiBase}/payments`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": apiKey,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Idempotency-Key": idempotencyKey
  },
  body
});

console.log(response.status, await response.json());

{
  "payment_id": "0198f0d4-15cb-7c98-ae52-4dd112dc14cc",
  "status": "PENDING",
  "created_at": "2026-08-17T11:42:16.921Z",
  "client_action": {
    "type": "redirect",
    "url": "https://spqr-payments.com/pay/0198f0d4-15cb-7c98-ae52-4dd112dc14cc#checkout_token=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "data": {
      "payment_page_id": "0198f0d4-15cb-7c98-ae52-4dd112dc14cc",
      "checkout_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

In the default redirect mode, client_action.url is an SPQR hosted checkout. Pass the complete client_action.url to the browser, including #checkout_token=…; do not reconstruct or strip its fragment. Keep client_action.data opaque and never render it as payment instructions.

Canonical request

Merchant API uses one signing protocol; no version header is required. The canonical UTF-8 string has five values, each followed by LF, including the last value. Trim leading and trailing whitespace from Idempotency-Key before signing. For requests without a body, including normal GET requests, hash an empty body. Use an empty fifth line when the key is absent. Use the exact escaped path and raw query string without decoding or reordering. Old signatures are rejected.

<UPPERCASE_METHOD>
<PATH_WITH_OPTIONAL_RAW_QUERY>
<LOWERCASE_HEX_SHA256_OF_BODY>
<X_TIMESTAMP>
<TRIMMED_IDEMPOTENCY_KEY_OR_EMPTY>

Request fields

Retrieve a PayIn

The full path and raw query are part of the HMAC signature. A pending operation may be refreshed before the response is returned.

H2H is available by default for supported payment methods and enabled merchant country/currency combinations, unless access has been disabled. A QR method name alone does not guarantee H2H support. Unsupported or unavailable combinations are rejected. Omitting checkout_mode keeps the standard redirect flow; there is no automatic fallback between modes.

Create a QR payment

Send a signed POST /payments with a new Idempotency-Key. Amounts are integer minor units: 12500 MYR is MYR 125.00. Payer fields depend on the method.

{
  "merchant": "acme_my",
  "amount": 12500,
  "currency": "MYR",
  "external_id": "order-8402",
  "country": "MY",
  "payment_method": "duitnowqr",
  "checkout_mode": "h2h",
  "qr_format": "url",
  "payer": { "customer_uid": "customer-184" }
}

qr_format accepts url (default) or base64, and is valid only with checkout_mode=h2h. New payments return HTTP 201; identical retries return HTTP 200 and the original operation. Changing mode or format with the same idempotency key returns HTTP 409.

Display a ready instruction

{
  "payment_id": "11111111-1111-4111-8111-111111111111",
  "status": "PENDING",
  "created_at": "2026-10-07T10:00:00Z",
  "checkout_mode": "h2h",
  "instruction_status": "ready",
  "client_action": {
    "type": "qr",
    "url": "https://api.spqr-payments.com/payment-assets/qr/<token>.png",
    "data": { "mime_type": "image/png", "expires_at": "2026-10-07T10:15:00Z" }
  }
}

Load client_action.url as an image. It grants access to one PNG and does not require HMAC, cookies, Origin or Referer. Treat the URL as sensitive and keep it out of logs. The image endpoint returns image/png with Cache-Control: no-store and X-Content-Type-Options: nosniff. An unknown token returns HTTP 404; an expired instruction or terminal payment returns HTTP 410.

{
  "type": "qr",
  "data": {
    "mime_type": "image/png",
    "expires_at": "2026-10-07T10:15:00Z",
    "image_base64": "<Base64-encoded PNG>"
  }
}

For Base64, use data:image/png;base64, followed by image_base64 as the image source. There is no url field. Both formats use the same saved PNG. Use the returned expires_at; deadlines vary by method and are not extended by retries or reads.

Wait for QR preparation

{
  "payment_id": "11111111-1111-4111-8111-111111111111",
  "status": "PENDING",
  "created_at": "2026-10-07T10:00:00Z",
  "checkout_mode": "h2h",
  "instruction_status": "pending"
}

The payment already exists. Poll the signed GET /payments/{id}?merchant={merchant_code} with the same merchant code used at creation and backoff to retrieve its instruction. Do not issue a second create while waiting. Stop polling when the instruction is ready, leaves pending, or the payment becomes terminal.

Only ready contains an image action. QR readiness is independent of payment status: ready does not mean paid, and a QR preparation error does not change monetary status. Continue using the standard signed payment webhooks.

{
  "merchant": "acme_my",
  "amount": 25000,
  "currency": "MYR",
  "external_id": "withdrawal-184",
  "country": "MY",
  "payment_method": "bank_transfer",
  "callback_url": "https://api.shop.example.com/webhooks/spqr",
  "recipient": {
    "bank_code": "MBBEMYKL",
    "account_name": "Alex Tan",
    "account_number": "5144229981"
  }
}

Retrieve a PayOut

Sign the exact GET query

GET requests use the same nested HMAC construction as create and retrieve calls. Hash an empty body and sign the path with the exact query order you send.

const path = "/capabilities?merchant=acme_my&operation_type=PAY_IN";
const timestamp = Math.floor(Date.now() / 1000).toString();
const bodyHash = crypto.createHash("sha256").update("").digest("hex");
const canonical = `GET\n${path}\n${bodyHash}\n${timestamp}\n\n`;
const inner = crypto.createHmac("sha256", merchantSecret).update(canonical).digest();
const signature = crypto.createHmac("sha256", apiClientSecret).update(inner).digest("hex");

const response = await fetch(`${apiBase}${path}`, {
  headers: {
    "X-Api-Key": apiKey,
    "X-Timestamp": timestamp,
    "X-Signature": signature
  }
});

Empty response examples

{
  "merchant": "acme_my",
  "operation_type": "PAY_OUT",
  "operation_enabled": false,
  "configured": false,
  "capabilities": []
}

{
  "merchant": "acme_my",
  "operation_type": "PAY_IN",
  "operation_enabled": true,
  "configured": false,
  "capabilities": []
}

Additional corridors can be enabled after commercial and operational approval. They are not listed as generally available until then.

NEW can also move directly to CANCELLED. The status_times object records the first UTC timestamp at which each state family was reached.

Resolution gives the reason

Status answers what happened; resolution explains why. Use both in operational dashboards and customer-support tooling.

Each operation keeps the X-Api-Key of the integration that created it. Verify its webhooks with that integration’s current client secret and your merchant secret. Retries keep the same key ID and event_id. Disabled, missing or foreign keys stop delivery; SPQR does not select another integration.

Rotating the secret under the same key ID affects the next delivery attempt. When replacing a key ID, keep the old client enabled until its operations and queued deliveries finish. Older operations and internal operations without an authenticated API client need an explicitly established binding before delivery.

Callback and return URLs are saved at first creation. Later merchant settings apply to new operations. Replaying an unchanged request with its original idempotency key returns the original operation; changing an explicitly supplied URL returns 409 idempotency_mismatch. An operation created without a callback keeps that absence.

{
  "event_id": "0198f0d9-d219-77e8-9419-c2dbfc54889d",
  "event_type": "payment.status_changed",
  "merchant": "acme_my",
  "operation_type": "payment",
  "operation_id": "0198f0d4-15cb-7c98-ae52-4dd112dc14cc",
  "external_id": "order-8402",
  "status": "SUCCEEDED",
  "resolution": "ok",
  "moderation_required": false,
  "status_times": {
    "new_at": "2026-08-17T11:42:16.921Z",
    "pending_at": "2026-08-17T11:42:17.244Z",
    "succeeded_at": "2026-08-17T11:42:31.808Z"
  },
  "amount": 12500,
  "paid_amount": 12500,
  "currency": "MYR"
}

SUCCEEDED covers full and partial payments. In the full example above, paid_amount equals amount. A partial payment can instead contain:

{ "status": "SUCCEEDED", "amount": 12500, "paid_amount": 7500 }

Credit the customer using paid_amount; check that it equals amount before fulfilling a full order. SPQR records the actually paid gross amount; net and fees are separate. A success confirmation without a separately reported paid amount is currently treated as full payment. Always use the returned paid_amount.

Persist event_id under a unique constraint with the event before returning 2xx. Repeated delivery must not repeat the business effect. Delivery order is not guaranteed: reconcile through GET instead of applying an older event over newer state. Default delivery is limited to eight attempts with exponential backoff bounded between 200 ms and five minutes; deployment settings may differ. Each attempt has a fresh timestamp and signature. There is no guaranteed elapsed-time delivery deadline; after exhaustion automatic retries stop. Recover missed state through GET by operation ID or external_id.

Verify the callback

Webhook signatures use four LF-terminated lines: the uppercase method, exact escaped request path with its raw query, SHA-256 hex digest of the raw body, and timestamp. The last LF is required. Use the received originalUrl without decoding the path, rebuilding the query, sorting parameters, or changing repeated parameters. Read the raw body before JSON parsing and compare the signature in constant time. This is the current webhook contract; decoded-path signatures are not supported.

function verifySPQRWebhook({ method, originalUrl, rawBody, headers, nowSeconds = Math.floor(Date.now() / 1000) }) {
  if (!headers || typeof method !== "string" || method.toUpperCase() !== "POST" ||
      typeof originalUrl !== "string" || !originalUrl.startsWith("/") ||
      !Buffer.isBuffer(rawBody) || !Number.isSafeInteger(nowSeconds)) return false;
  if (typeof apiKey !== "string" || !apiKey || headers["x-api-key"] !== apiKey) return false;
  const timestamp = headers["x-timestamp"];
  const received = headers["x-signature"];
  if (typeof timestamp !== "string" || !/^[0-9]+$/.test(timestamp) ||
      typeof received !== "string" || !/^[0-9a-f]{64}$/.test(received)) return false;
  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || Math.abs(nowSeconds - seconds) > 300) return false;
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
  const canonical = `${method.toUpperCase()}\n${originalUrl}\n${bodyHash}\n${timestamp}\n`;
  const inner = crypto.createHmac("sha256", merchantSecret).update(canonical).digest();
  const expected = crypto.createHmac("sha256", apiClientSecret).update(inner).digest();
  return crypto.timingSafeEqual(Buffer.from(received, "hex"), expected);
}

Persistent event inbox

After signature verification, store each event in PostgreSQL. A duplicate insert returns no row; acknowledge it without scheduling the business work again. Keep the inbox and a durable work item in the same transaction. The worker also needs an idempotent business effect. In-memory sets lose deduplication after restart.

CREATE TABLE spqr_webhook_inbox (
  event_id uuid PRIMARY KEY,
  payload jsonb NOT NULL,
  received_at timestamptz NOT NULL DEFAULT now(),
  processed_at timestamptz
);

-- Bind event_id and the verified JSON body as parameters.
INSERT INTO spqr_webhook_inbox (event_id, payload)
VALUES ($1, $2)
ON CONFLICT (event_id) DO NOTHING
RETURNING event_id;

PayOut events use payout.status_changed, operation_type: "payout", and also include the original recipient object.

Recover an operation

The merchant assigns external_id (1–128 characters after trimming). It is unique for that merchant separately for PayIn and PayOut, regardless of currency or method, including FAILED and CANCELLED operations. Matching is case-sensitive; leading and trailing whitespace is trimmed. A new key with an existing external ID returns HTTP 409 external_id_conflict, even when the body is identical.

Use signed GET /payments?merchant=acme_my&external_id=order-8402 or GET /payouts?merchant=acme_my&external_id=withdrawal-184 if you lost the SPQR ID. URL-encode query values before signing the exact path and query. The response is the same as GET by operation ID; unknown IDs return 404. GET also restores a saved SPQR redirect action for an unfinished PayIn without creating another operation.

An error after acceptance includes error.operation with operation_type, operation_id, external_id and the current status (null when state cannot be read after the failure). The original key is already claimed. An uncertain result must be recovered with that key; after a terminal rejection, a new attempt requires both a new external ID and a new key. An identical replay can return HTTP 200 with the saved CANCELLED operation after the initial rejection.

{
  "error": {
    "code": "merchant_balance_insufficient",
    "message": "merchant balance is insufficient",
    "operation": {
      "operation_type": "payout",
      "operation_id": "0198f0d4-15cb-7c98-ae52-4dd112dc14cc",
      "external_id": "withdrawal-184",
      "status": "CANCELLED"
    }
  }
}