Use this skill for Betterpay payment gateway integration work.
Source
Read references/betterpay-api.md before giving factual API guidance or writing integration code. It covers:
- PRO vs LITE, environments and hosts, auth
- Both hash algorithms, the endpoint catalogue
- Standard and Direct Payment fields, callbacks, requery
- Refunds, reports, payment links, invoices
- Rate limit, sandbox data, errors
Read references/betterpay-recurring.md for e-Mandate direct debit, OCBC collection batches or LITE card recurring.
Read references/betterpay-tokenization.md for card tokens, token charge, batch charge, token pre-auth or Card Pre-authorization (MPGS).
Read references/betterpay-codes.md for any status, error, bank, channel or enum value.
Read references/account-setup.md for registration, where keys live, API Management settings, sandbox vs live, env vars, method activation, plugins or settlement.
Read references/source-map.md to pick the right official docs anchor or Postman collection.
Core Workflow
- Identify the product from the merchant ID: an
Rprefix (e.g.R1001) is LITE (HMAC-SHA256); numeric (e.g.10001) is PRO (MD5). - Identify the environment: sandbox
https://www.demo.betterpay.me, or production. Confirm the production paths in the logged-in docs. - Identify the surface: Standard Payment (hosted checkout), Direct Payment (bank/e-wallet/card/DuitNow QR), payment link, bill, invoice, recurring, token, pre-auth or plugin.
- Configure API Management: callback URL, Whitelist Domain (it must match the
callback_url_behost), and return URLs. - Create a local pending order with a unique invoice (max 14 chars, no
& ' -) and the amount in ringgit with 2 decimals. - Build the request and hash server-side with the endpoint's exact field order (PRO) or the sorted-values rule (LITE).
- Send the browser via form POST (Standard) or redirect to
payment_url(Direct withrespond=1). - Treat
callback_url_fe_succ/callback_url_fe_failas UX only. - On the
callback_url_bePOST:- Verify the hash.
- Check invoice, amount and
txn_status. - Settle idempotently.
- Reply with plain
OK.
- Requery (Get Payment Status) when no callback arrives or the status is pending.
Core Facts
- Betterpay is the QlicknPay stack renamed. The docs say Betterpay.me and qnp.com hosts are both valid. The docs still say QlicknPay in many places.
- Docs:
https://www.betterpay.me/docs/(one page, endpoints behind login). Sandbox paths are inhttps://github.com/betterpayme/POSTMAN-APIs. - PRO production host per the official WP plugin:
https://www.betterpay.me. LITE plugin checkout:https://lite.betterpay.me/api/merchant/v1/checkout. - Auth:
merchant_id+hashin the body. The API key only signs. HTTPS only. Every request is hashed. - PRO Standard hash:
md5(api|merchant_id|invoice|amount|payment_desc|currency). - PRO callback check:
md5(api . trx_id . invoice_no . txn_status . msg)with no separators.trx_idisfpx_fpxTxnId,paypal_trx_id,mastercard_trx_idorothers_trx_id. - Some PRO calls put
merchant_idbefore the API key: requery, refunds, refund status. - LITE hash: sort all sent fields except
hashby name, concatenate the values, remove spaces, thenhash_hmac('sha256', s, API_KEY). Verify the callback the same way over the received fields. - Status codes:
- PRO:
00approved,09pending,99pending authorization (B2B). - LITE:
00success,11failed,22pending,failedcancelled.
- PRO:
- Amount limits: RM1.50 minimum and under RM30,000 (B2C). Amounts are strings with 2 decimals.
- Callback retry: Betterpay resends at most 3 times every 10 minutes until it gets
OK. - Rate limit: GET endpoints share 100 requests per 5 minutes per IP or account. Over the limit gives HTTP 429
{"response":"99",...}. - FPX refund API: only with your own FPX seller ID, max 10 per request, within 5 days. DuitNow QR refunds have their own endpoint.
Critical Rules
- Keep the API key server-side. Never put it in the browser form. Compute the hash on the server.
- Never mix PRO and LITE hashing or endpoints. Never mix sandbox and live keys.
- Use the exact per-endpoint field order from the reference tables. Never guess an order.
- Hash the plain values exactly as sent (the PHP samples
urldecodeeach value). Send amounts as strings. - Never fulfil from the return URL or a client-side message. Fulfil only from a hash-verified backend callback or a requery.
- Compare hashes in constant time. Then check that the invoice exists, the amount and currency match, and
txn_statusis the success code. - Make the callback handler idempotent and always reply plain
OKonce the callback is stored. Retries and duplicates happen. - Keep
callback_url_beon the Whitelist Domain host, or the payment is rejected ("Invalid URL variable specified"). - Each invoice must be unique per transaction. Retrying with the same invoice fails.
- Treat endpoints marked "Not published" and the doc/Postman conflicts in the references as unconfirmed. Test in sandbox and confirm with support.
Completion Criteria
A Betterpay integration is done only when:
- The product (PRO/LITE), environment, host, merchant ID and API key come from config, never hardcoded.
- Payment creation and hashing run server-side with the documented field order (PRO) or sort rule (LITE).
- API Management has the callback URL, Whitelist Domain and return URLs for the right environment.
- The callback handler:
- verifies the hash over the documented input,
- checks invoice, amount, currency and
txn_status, - settles once,
- replies
OK.
- Pending results (
09,99,22) and missing callbacks are resolved by Get Payment Status, idempotently. - Tests cover a bad hash, a replayed callback, a wrong amount, an unknown invoice, a failed/cancelled status, a pending status and a successful payment.
- Deployment docs list
BETTERPAY_PRODUCT,BETTERPAY_ENV,BETTERPAY_BASE_URL,BETTERPAY_MERCHANT_ID,BETTERPAY_API_KEYand the callback/return URLs, with sandbox and live kept apart.
Loophole Review Loop
When asked whether a Betterpay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser form POST, hosted checkout, bank/e-wallet page, return URLs, backend creator, Betterpay API, callback receiver, database, fulfilment, refund job, API Management settings, plugin.
- Check bypasses:
- fake return redirect, forged callback, hash built from parsed or re-encoded values
- wrong field order, PRO/LITE mix, sandbox/live key mix
- wrong amount or invoice, reused invoice
- pending treated as paid, duplicate callback
- missing
OKcausing retries, callback host not whitelisted - stale requery, refund replay,
failed(cancel) treated as error-free
- Add fixes:
- server-side hashing, local pending order first
- constant-time compare, strict amount/invoice/status checks
- durable callback log, idempotent settlement
- separate env config, requery fallback, sandbox tests for every unconfirmed formula
- Re-read the relevant section of
references/betterpay-api.md(or the recurring/tokenization/codes file) for any gap. - State remaining uncertainty: production endpoint paths (behind login), LITE callback field set, LITE payment link hash conflict, plan-to-product mapping, enabled channels, refund eligibility, settlement timing.