Use this skill for Tulus payment gateway integration work. Tulus Digital Sdn Bhd runs one gateway under two brands, Tulus and SnapNPay; the API, field names and signing are the same.
Source
Read references/tulus-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, hosts, auth, checkout fields, the signature algorithm with verified test vectors, callback fields, report API, QR generators, and the known doc inconsistencies.
Read references/tulus-codes.md for the full fpx_debit_auth_code table, status mapping, zakat agency codes, zakat type and state enums, and form schema fields.
Read references/tulus-partner-apis.md only when the user is a partner pushing transactions into Tulus (ADB, Grab webhooks) or customising receipts and receipt emails.
Read references/account-setup.md for onboarding, where the AuthToken and API key live, staging vs production, env var names, and settlement notes.
Read references/source-map.md to pick the right official page.
Core Workflow
- Confirm the agency code (assigned at onboarding) and that the merchant has an API key (UUID) from the merchant dashboard. The API key is required to sign orders and verify callbacks.
- Confirm the environment and checkout host with Tulus (see "Hosts" in
tulus-api.md; docs and live behaviour differ). - Create a local pending payment keyed by your
refNobefore redirecting. - Server-side, build the order fields
agency,refNo,amount,email,returnUrl(plus optionalcancelUrl), addexp = now + 60, sign, and render an auto-submitting POST form to/v2/checkout. - Handle both POSTs on
returnUrl: the direct callback (hassignature, server-to-server, authoritative) and the indirect browser return (nosignature, display only). - Verify the direct callback signature over all POST fields except
signature, sorted, Gourl.QueryEscapeencoding, no path, noexp. - Settle only on verified
status=success, after matchingrefNo,agencyand the netamount; answer HTTP 200 quickly. - Reconcile pending or missed payments with the signed Report API (
/api/report/v1/fpxrequestor/api/report/v1/payment).
Core Facts
- Documented checkout:
POST https://tulus.my/v2/checkout,application/x-www-form-urlencoded. On 2026-10-21 that URL returned 404 whilehttps://pay.tulus.my/v2/checkoutanswered; the SDK playground posts tohttps://pay.tulus.my/(production) andhttps://paydev.tulus.my/(staging, FPX test banks). Confirm the host with Tulus. - Reporting host:
https://reports.tulus.my(also the merchant dashboard). - Auth: AuthToken JWT (
Authorization: Bearer) for reports, copied from the dashboard; or per-agency API key UUID used only as an HMAC key. The oldtoken/ username+password method is deprecated. - Signature:
HMAC-SHA256(message, key)hex, first 16 characters. Key is the UUID with dashes removed, hex-decoded to 16 raw bytes. - Outbound message:
<path>?<ksorted RFC 3986 query including exp>, for GET reports and POST checkout/QR alike. Checkout path is/v2/checkout. - Callback message: ksorted
k=v&...of all POST fields exceptsignature, Gourl.QueryEscapeencoding (space is+), no path, noexp. amountis a ringgit string with 2 decimals; minimum1.00(FPX B2B2.00).refNomust not contain~;~appends extraData.- Direct callback
status:success,pending,failed. Retried about every 30 seconds until HTTP 2xx. - Direct callback
amountis net;addChargeis the platform fee; indirect returnamountis gross. - Unsigned or wrongly signed checkouts are rejected with HTTP 403 in production.
- Live test payments should use an amount ending in
12.34. - Refunds, cancel/void, recurring and tokenisation APIs: not documented in official docs (checked 2026-10-21).
Critical Rules
- Keep the API key and AuthToken server-side only; the key never goes on the wire.
- Never fulfil from the indirect browser return or from
cancelUrl. - Never HMAC the ASCII UUID, never use the full 64-char digest, never add
expor a path when verifying callbacks. - Do not add unsigned fields (for example a CSRF
_token) to the checkout form; every posted field is checked. - Exempt
returnUrlfrom CSRF; respond 200 without redirects. - Compare signatures in constant time.
- Settle idempotently: the same success can arrive more than once (retries and dashboard re-sends); a recorded success never regresses.
- Cross-check the signed net
amountagainst your stored amount. - Read
fpx.payment_methodto tell FPX from card (mpgs) and others; field names stayfpx_*for all methods. - Do not use the downloadable WooCommerce plugin as a reference for verification: its signature check is disabled and it does not add
exp.
Completion Criteria
A Tulus integration is done only when:
- The signer passes both official test vectors in
tulus-api.md. - Checkout is signed server-side at redirect time (60-second
exp) and posts only signed fields. returnUrlis public HTTPS, CSRF-exempt, and handles direct and indirect POSTs separately.- Direct callbacks are verified, matched on
refNo,agency, netamount, and settled once onsuccess. pendingstays pending; a scheduled job reconciles via the signed Report API.- Tests cover bad signature (403), replayed success (no double fulfil), tampered amount, unsigned indirect POST, and
pendingthensuccess. - Deployment docs list
TULUS_AGENCY,TULUS_API_KEY,TULUS_CHECKOUT_URL,TULUS_REPORT_URL,TULUS_RETURN_URL, and staging vs production values.
Loophole Review Loop
When asked whether a Tulus strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: checkout form, buyer browser, Tulus checkout host, bank/FPX, direct callback, indirect return,
cancelUrl, database, fulfilment job, Report API, merchant dashboard. - Check bypasses: forged indirect POST, callback without
signature, signature over the ASCII key, wrong encoding of~or space, staleexp, unsigned extra form field, amount gross vs net confusion, wrong agency, duplicate success, latependingaftersuccess, wrong checkout host, staging key on production. - Add fixes: server-side signing at redirect, constant-time verify, strict refNo/agency/amount match, row lock plus idempotent fulfil, terminal-state guard, signed Report API fallback, separate env config.
- Re-read
references/tulus-api.mdsections relevant to any gap. - State remaining uncertainty: checkout host, staging credentials, payment methods and fees enabled for the agency, settlement timing, and any undocumented refund process.