Use this skill for Qashier (QashierPay Online and QashierPay terminal) payment integration work.
Source
Read references/qashier-api.md before giving factual API guidance or writing integration code. It is the entry point: environments, auth, endpoint catalogue, Checkout Session fields, webhooks and the exact signature algorithm, refunds, errors, rate limits, test cards, and documented gaps.
Read references/qashier-instore.md only when the user integrates their own POS with a QashierPay card terminal (partner API with x-qashier-partner and x-qashier-sign).
Read references/account-setup.md when the user asks how to sign up, where keys come from, staging vs production, payment method activation, plug-ins, Pay-by-Link, settlement, or pricing.
Read references/source-map.md to pick the right official page or to check coverage.
Core Workflow
- Identify the surface: QashierPay Online hosted checkout (API), plug-in (Shopify, WooCommerce, Wix), Pay-by-Link (no code), or in-store terminal partner API.
- Identify environment: staging (
api.staging.qashier.com) or production (api.qashier.com), with matching API key. - Create a local pending order first, with amount in sen and currency
MYR. - Create the Checkout Session server-side:
POST /checkout/sessionswith Basic Auth (API key as username, empty password) and anIdempotency-Keyheader. - Store the returned session
idagainst the local order, then redirect the customer (HTTP 303) to the returnedurl. - Treat
success_urlandreturn_urlas browser UX only; never fulfil from them. - Verify
X-Qashier-Signatureon every webhook over the raw request body before parsing JSON. - On
checkout.session.completed, fulfil only whendata.object.payment_statusispaid;unpaidmeans the attempt was declined. - Re-fetch the session with
GET /checkout/sessions/{id}and match id, amount, currency, status before settling idempotently. - For abandonment, retrieve the session after
expires_atand confirmstatus: expired; no webhook fires for natural expiry.
Core Facts
- Online API base: production
https://api.qashier.com/v3/payment/qpay, staginghttps://api.staging.qashier.com/v3/payment/qpay. - Auth: HTTP Basic, API key as username, empty password (
Authorization: Basic base64("<API_KEY>:")). Keys are managed in the Qashier Dashboard. - Endpoints:
POST /checkout/sessions,GET /checkout/sessions,GET /checkout/sessions/{id},POST /checkout/sessions/{id}/expire,POST /refund. - Create requires
currency,line_items[](unit_amountinteger in cents,quantitylimited to 1),return_url,success_url; optionalexpires_at,customer_email. expires_atis 30 minutes to 24 hours after creation; default 24 hours.- Session
status:open,complete,expired.payment_status:paid,unpaid. - Webhook events:
checkout.session.completed,checkout.session.expired(only when you call expire), and refund updates. - Signature: header
t=<ts>,v1=<hex>;signing_key = SHA256(webhook_secret);v1 = HMAC_SHA256(signing_key, "<t>.<raw_body>"); constant-time compare. - Refunds:
POST /refundwithsessionIdand optionalamountin cents; async, statuspending,succeeded,failed. - Idempotency keys: max 255 chars, kept 24 hours, reuse with different params returns 409
idempotency_error. - Rate limit: 100 requests per second per API key; 429
rate_limit_error. - Merchants do not pick payment methods per session; checkout shows what the account has enabled.
Critical Rules
- Keep the API key and webhook secret server-side only.
- Never fulfil on the event name alone;
checkout.session.completedis sent for declines too. - Verify the signature over the exact raw bytes received; do not re-serialize JSON.
- Do not infer abandonment from webhook silence; retrieve the session and check
status. - Use separate keys, webhook URLs, and secrets for staging and production.
- Make settlement idempotent on session
id(and webhook eventid); duplicates must not double-fulfil. - Send amounts as integers in sen (RM20.00 =
2000); confirm amount andMYRcurrency on settlement. - Ignore the docs page
/docs/api/payments-example(POST /v1/payments, Bearer token): it is a template example, not the real API. - Confirm documented gaps (webhook URL registration, secret location, signing key encoding, timestamp tolerance) with Qashier before production; see
references/qashier-api.md.
Completion Criteria
A Qashier integration is done only when:
- Checkout Session creation runs server-side with Basic Auth and an
Idempotency-Key. - The local order stores session
id, expected amount, currency, environment, and state before redirect. - The webhook handler verifies
X-Qashier-Signatureover the raw body with the correct environment secret, constant-time. - Settlement requires
payment_status: paid, matching session id, amount, and currency, confirmed by a server-side retrieve. - Declines (
unpaid), duplicate events, delayed webhooks, and natural expiry are handled idempotently. - Refunds use
POST /refund, and refund state is reconciled from refund webhooks orrefund_details. - Tests cover invalid signature, replayed event, declined card (
unpaid), wrong amount/currency, expired session, and a paid session, using the documented test cards on staging. - Deployment docs list
QASHIER_API_KEY,QASHIER_WEBHOOK_SECRET,QASHIER_API_BASE, success/return URLs, webhook URL, and staging/production separation.
Loophole Review Loop
When asked whether a Qashier strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser, success/return pages, backend session creator, Qashier API, webhook receiver, raw-body parser, database, fulfilment job, refund job, dashboard settings, and payment method activation.
- Check bypasses: fake success redirect, forged webhook, signature over parsed JSON, wrong secret or key encoding, staging/live mix,
completedtreated as paid, wrong amount or currency, replayed event with old timestamp, duplicate webhook, abandoned session marked failed too early, refund double-sent, disabled payment method. - Add fixes: server-side session creation, local pending order first, raw-body HMAC verification, constant-time compare, timestamp age check, retrieve-before-settle, strict amount/currency/id checks, durable event log, idempotency keys, separate environment config.
- Re-read
references/qashier-api.mdsections relevant to any gap. - State remaining uncertainty where it depends on undocumented items (webhook URL setup, secret location, timestamp tolerance, refund idempotency), account approval, enabled methods, settlement timing, or pricing.