setup-tulus skill
Integrate and debug Tulus payment gateway services including FPX, cards, and QR payments using PHP SDKs and Laravel.
- GitHub stars
- 76
- Files
- 7
- Last commit
- Oct 21, 2026
- License
- —
- Allowed tools
- —
What does the setup-tulus skill do?
setup-tulus integrates and debug Tulus payment gateway services including FPX, cards, and QR payments using PHP SDKs and Laravel.
Summary generated from the skill's SKILL.md.
About the setup-tulus skill
Integrating Tulus or SnapNPay payment gateways into PHP or Laravel applications is what this skill enables. Developers use it to build secure checkout flows for FPX, credit cards, DuitNow, and QR payments. The skill provides guidance on generating HMAC-SHA256 truncated signatures using a UUID API key, constructing auto-submitting POST forms for the /v2/checkout endpoint, and managing both direct server-to-server callbacks and indirect browser returns.
An agent should load this skill when a developer needs to implement payment reconciliation via the Report API, configure staging versus production environments, or debug signature mismatches. It relies on specific reference documentation covering endpoint catalogues, agency codes, and status mapping. The skill helps ensure production readiness by enforcing strict rules, such as verifying the net amount against stored records and handling idempotent settlements to prevent duplicate fulfillment.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the setup-tulus skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the setup-tulus skill in Claude Code
~/.claude/skills/setup-tulus/SKILL.md
$ npx degit afu-it/malaysia-payment-gateway/setup-tulus ~/.claude/skills/setup-tulusInstall the setup-tulus skill in Claude Code (project)
.claude/skills/setup-tulus/SKILL.md
$ npx degit afu-it/malaysia-payment-gateway/setup-tulus .claude/skills/setup-tulusInstall the setup-tulus skill in Codex
~/.agents/skills/setup-tulus/SKILL.md
$ npx degit afu-it/malaysia-payment-gateway/setup-tulus ~/.agents/skills/setup-tulusInstall the setup-tulus skill in Gemini CLI
~/.gemini/skills/setup-tulus/SKILL.md
$ npx degit afu-it/malaysia-payment-gateway/setup-tulus ~/.gemini/skills/setup-tulusInstall the setup-tulus skill in Claude.ai
npx degit afu-it/malaysia-payment-gateway/setup-tulus setup-tulus && zip -r setup-tulus.zip setup-tulus # claude.ai → Customize → Skills → + → Create skill → Upload a skill → setup-tulus.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableafu-it/malaysia-payment-gateway/setup-tulus is public and reachablegithub.com/afu-it/malaysia-payment-gateway/tree/HEAD/setup-t ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit 2026-10-21github.com/afu-it/malaysia-payment-gateway/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/afu-it/malaysia-payment-gateway/blob/HEAD/setup-t ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/afu-it/malaysia-payment-gateway/blob/HEAD/setup-t ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 82 linesgithub.com/afu-it/malaysia-payment-gateway/blob/HEAD/setup-t ↗Pass
SKILL.md
View on GitHubTulus (SnapNPay) Payment Gateway
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.
Files in this skill
7setup-tulus skill questions
How do I install the setup-tulus skill in Claude Code?
Run npx degit afu-it/malaysia-payment-gateway/setup-tulus ~/.claude/skills/setup-tulus. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the setup-tulus skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I authenticate with the Tulus Report API?
Use an AuthToken JWT in the Authorization header, which can be copied from the merchant dashboard.
What is the correct way to sign a Tulus checkout order?
Build the order fields, add an expiration (exp) set to 60 seconds from now, sign the message using HMAC-SHA256 with the UUID API key (hex-decoded to 16 raw bytes), and render an auto-submitting POST form.
How should I handle the returnUrl callback?
You must distinguish between the direct authoritative callback (which includes a signature) and the indirect browser return (which does not). Only settle payments based on the verified direct callback.
What is the signature algorithm for Tulus?
The signature is an HMAC-SHA256 hex digest, truncated to the first 16 characters, using the UUID API key as 16 raw bytes.