Use this skill for SecurePay Sdn Bhd (securepay.my) payment gateway integration work.
Source
Read references/securepay-api.md before giving factual API guidance or writing integration code. It is the entry point: version choice, environments, credentials, the full endpoint catalogue, v1 payment creation, the request checksum, callback/redirect fields and checksum verification (with test vectors), status, list, search, errors and gaps.
Read references/securepay-v2.md when the merchant uses API v2 (SecurePay Console, client ID/secret, auth_token, payment intents, DuitNow, eMandate, split settlement, closed wallet, memberships, partner API, certificates).
Read references/securepay-codes.md for FPX bank codes, status values, auth codes, enums and sandbox test banks.
Read references/account-setup.md for registration, documents, where credentials live, sandbox vs live, interface settings, settlement schedule, refunds policy, plugins and support.
Read references/source-map.md to pick the right official page, and for docs coverage notes.
Core Workflow
- Pick the API version. SecurePay's docs hub marks v1 as the production API and v2 as a preview. Default to v1 unless the merchant's account is on SecurePay Console (v2 client ID/secret).
- Identify environment: sandbox or production. v1 sandbox
https://sandbox.securepay.my/api, productionhttps://securepay.my/api. - Get the interface credentials for that environment: API UID, Auth Token, Checksum Token (v1).
- Create a local pending order with a unique
order_numberand the expected amount before calling SecurePay. - v1: build the request checksum, then POST the form fields to
/v1/payments(usually as an auto-submitted browser form, like the official plugin), or create a Payment Session and redirect topayment_url. - Treat
redirect_urlas browser UX only. Fulfil from the server-to-servercallback_urlPOST. - Verify the callback
checksum: sort all received keys ascending (excludingchecksum), join values with|, HMAC-SHA256 with the Checksum Token, constant-time compare. - Requery
GET /v1/payments/status/:order_numberwith Basic auth before settling, and confirmpayment_status,transaction_amount_received, currency andorder_number. - Settle idempotently. For FPX B2B1 treat
fpx_debit_auth_code99as pending; wait for the later00callback. - Reconcile with
GET /v1/transactions/listor/v1/transactions/searchwhen callbacks are missed.
Core Facts
- v1 create payment:
POST /v1/payments(form-encoded). v1 Payment Session (beta):POST /apis/paymentsreturning JSONpayment_url. - v1 request checksum string order:
buyer_email|buyer_name|buyer_phone|callback_url|order_number|product_description|redirect_url|transaction_amount|uid, HMAC-SHA256 hex, key = Checksum Token. Empty optional values keep an empty slot. - v1 amounts are ringgit with two decimals (
1540.40). v2 payment intents useamountin cents (154040). - v1 auth for status/list/search/validate/session: HTTP Basic
uid:auth_token. The payment form POST carriestoken(Auth Token) andchecksumas fields. - Validate credentials:
POST /v1/merchants/validatewith Basic auth andchecksum_token. - Public FPX bank list (no auth):
GET /public/v1/banks/b2cand/public/v1/banks/b2b, optional?status=online|offline. Discard a response whoseVerifySignis nottrue. - Callback/redirect are POSTed with fields such as
payment_status,transaction_amount,transaction_amount_received,order_number,exchange_number,fpx_debit_auth_code,checksum. - v2 base URLs: production
https://console.securepay.my/api, staginghttps://sandbox.securepay.dev/api. Auth:POST /v1/authwith Basicclient_id:client_secret, thenAuthorization: Bearer <auth_token>. - No refund, void or capture API is documented. Refunds are manual via support (Refund & Cancellation Policy).
- Settlement is T+1 business day per SecurePay; cut-off 11:59pm MYT; Friday to Sunday settle Monday.
- Rate limits and callback source IPs are not documented.
Critical Rules
- Keep Auth Token, Checksum Token, client secret and partner secrets server-side. The browser form may carry
tokenandchecksum(as the official plugin does) but never the Checksum Token itself. - Compute the request checksum server-side; never let the browser supply amount or checksum inputs.
- Do not mark paid from the redirect POST, the SecurePay status page, or
payment_statusalone. The official WooCommerce plugin does not verify the callback checksum; do not copy that. - Verify the callback checksum over the exact received parameters (all keys, including ones you do not use). SecurePay says params keep being added, so never hard-code the key list.
- Strip zero-width characters if you copy strings from the docs; several doc samples contain U+200B.
- Always requery status server-side and check amount, currency (
MYR),order_numberand environment before settling. - Keep
order_numberunique per attempt; status lookups use it. - Use sandbox credentials only with sandbox URLs, and production with production.
- v2 callbacks carry a nested
paymentobject and the docs do not define how to flatten it for the checksum; settle v2 from an authenticated status requery. - Confirm live payment method availability, pricing, settlement arrangement and B2B1 enablement with SecurePay before claiming production certainty.
Completion Criteria
A SecurePay integration is done only when:
- Payment creation runs from server-generated fields with a correct HMAC-SHA256 checksum, or via Payment Session / v2 intent created server-side.
- Redirect handling only shows status; it does not fulfil.
- Callback handler verifies
checksumwith the Checksum Token over all received params, constant-time. - Settlement requeries status and checks
order_number,payment_status,transaction_amount_received, currency and environment. - Duplicate callbacks, redirect-before-callback, B2B1
99then00, and failed payments are idempotent. - Tests cover bad checksum, tampered amount, unknown order, failed payment, duplicate callback, and the documented checksum test vectors.
- Deployment docs list
SECUREPAY_UID,SECUREPAY_AUTH_TOKEN,SECUREPAY_CHECKSUM_TOKEN(or v2SECUREPAY_CLIENT_ID,SECUREPAY_CLIENT_SECRET), base URL, callback URL, redirect URL and sandbox/live separation.
Loophole Review Loop
When asked whether a SecurePay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser form POST, SecurePay bank selection page, redirect POST, callback POST, checksum verifier, status requery, database, fulfilment job, dashboard interface settings, settlement account.
- Check bypasses: forged redirect POST, forged callback without checksum, checksum over a hard-coded key subset, wrong Checksum Token (other interface), sandbox/live mix, tampered
transaction_amount, reusedorder_number, B2B199treated as paid, duplicate callback, callback before order commit, offline bank selected, USD Payment Session amount converted to MYR, nested v2 payload. - Add fixes: server-side checksum, local pending order first, full-param checksum verification, constant-time compare, status requery, strict amount/currency/order checks, unique order numbers, idempotent settle, per-environment config, reconciliation via list/search.
- Re-read
references/securepay-api.md(andsecurepay-v2.mdfor v2) for any gap. - State remaining uncertainty: undocumented v1
/v1/paymentsresponse format,uidas a form field, v2 response bodies, v2 checksum for nested payloads, PQC request signing, rate limits, callback IPs, retry policy, pricing.