Use this skill for Finexus online payments (PayMaster) and Finexus Kayaaku POS terminal integrations.
Source
Read references/finexus-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, field tables, MTIs, the secure hash method with test vectors, amount rules, query, reversal and refund, DuitNow Pay, QR, recurring, pre-auth, status codes and plugin cautions.
Read references/account-setup.md for registration, credentials, sandbox vs live, env var names, method activation, pricing link and settlement.
Read references/finexus-kayaaku-pos.md only for in-person terminals (App-to-App, Bluetooth, USB, HTTP JWE, pre-auth HTTPS, UCAT).
Read references/source-map.md to pick the official page for a topic and to see doc coverage.
Core Workflow
- Identify environment (sandbox or production) and the host Finexus issued; never guess the production host.
- Identify surface: UPP hosted page (default), DuitNow Pay direct, dynamic QR, consumer presented QR, static QR, card token / recurring, pre-auth, plugin, or Kayaaku POS.
- Choose MPI library or raw PayMaster API. Both send the same
name=valuemessages. - Create a local pending payment with a unique
f263_MRN, expected amount and currency before redirecting. - Build the 0280 message server side, hash it, and send the browser to
/upp/faces/upp/payment.xhtml. - On the 0290 return (browser GET), verify
t002_SHV, then match MRN, amount and currency. - Confirm with a 0780 query (
requery0780.xhtml) before fulfilling; only trust it whenf274_QRespCode=00. - Settle idempotently on result
00for the mode inf283_UPP_PM; keep22/68/ no response as pending and keep polling. - Handle dynamic QR via the server-to-server MT0250 callback (verify hash, reply HTTP 200) plus query fallback.
- Use 0400 for void or reversal same day and refund (
993000) after settlement.
Core Facts
- Messages are
name=valuefields: headerh001_MTI..h004_TTM, bodyfNNN_*, trailert001_SHT=SH2,t002_SHV. - Hash:
UPPER(HEX(HMAC_SHA256(key=SecretKey, data=<fields joined by & without trailer> + SecretKey))). - Hash raw values, keep empty fields, exclude
f289_*andf290_Signature; verify responses over the decoded query string before&t001_SHT=. - Docs test vector: key
00112233445566778899AABBCCDDEEFF, 0880 example gives6C825DC0...3A962892. - MPI flags a bad hash as
TxnStatDetCde=5015. - Amount
f007_TxnAmtis 12 digits with implied decimals (f019_ExpTxnAmt=2); RM 1.00 =000000000100; currency458, countryMY, serviceFNX. - UPP payment 0280 to 0290, query 0780 to 0790, reversal / refund 0400 to 0410, DuitNow Pay 0880 to 0890, bank listing 0360 to 0370, dynamic QR 0180 to 0190 plus 0250 callback.
- Paths:
/upp/faces/upp/payment.xhtml,/upp/faces/upp/requery0780.xhtml,/upp/faces/reversal0400.xhtml,/upp/faces/duitnowpaypayment.xhtml,/upp/faces/banklisting.xhtml,/upp/faces/generateQrPayload.xhtml. - Docs mask hosts as
xxx.finexusgroup.com; examples usesandbox.finexusgroup.com; the MPI ships withdev.finexusgroup.com:10501. - Query rule: no response after 30 s, query every 5 s up to 30 min (dynamic QR: up to 5 min).
- Production blocks an IP that floods requests for 1 min, plus 1 min per further attempt.
- Void / reversal before settlement (same day); refund after; DuitNow QR is refund only; no partial reversal.
- Onboarding is through the MyXaaS application form; Finexus issues MID, Secret Key, TID and URLs.
Critical Rules
- Keep the Secret Key, MID config, RSA and EC private keys server side only.
- Never mark paid from the browser return alone; verify the hash and confirm with a 0780 query.
- Do not copy the official WooCommerce plugin's return handler: it trusts
result_mode=succfrom the URL without a hash check. - Use constant-time comparison for
t002_SHV(the plugin uses==). - Hash fields in the documented message order; if a hash fails, check order, empty fields, URL decoding (
+to space) and the^substitution for&in return URLs. - Match
f263_MRN,f007_TxnAmt,f010_CurrCodeandf001_MIDagainst the local record before settling. - Make settlement idempotent across return, query, QR callback and static QR push (dedupe
trxRefNo). - Treat pending (
22), timeout (68), query96and missing responses as unknown, not failed. - Use a new MRN for each payment and for each DuitNow refund.
- Never invent production hosts, test cards, fees or settlement times; ask Finexus.
Completion Criteria
A Finexus integration is done only when:
- 0280 (or 0880 / 0180) messages are built and hashed server side with the correct MID and Secret Key per environment.
- The return handler verifies
t002_SHVwith constant-time compare and rejects mismatches. - Settlement runs only after a 0780 query with
f274_QRespCode=00and result00, or a verified QR callback, and checks MRN, amount, currency and MID. - Pending and timeout outcomes are polled per the documented schedule and stop cleanly.
- Reversal and refund use 0400 with the right processing code and are idempotent.
- Tests cover the docs hash vector, bad hash, wrong amount, wrong MRN, duplicate return or callback, pending then success, and failed codes.
- Deployment config has
FINEXUS_MERCHANT_ID,FINEXUS_SECRET_KEY,FINEXUS_PAYMASTER_BASE_URL, return URLs, and sandbox / live separation.
Loophole Review Loop
When asked whether a Finexus strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser redirect, return URLs, backend message builder, Secret Key storage, PayMaster host, query endpoint, QR callback, static QR push, database, fulfilment job, refund job, plugin code, Kayaaku POS device.
- Check bypasses: forged return query, replayed success URL, hash over wrong order or encoded values, wrong key or environment, amount or currency swap, reused MRN, pending treated as failed, query
12treated as failed too early, duplicate callback, refund twice, pluginresult_modetrust, rate limit block during polling. - Add fixes: server-side hashing, constant-time verify, query confirmation, strict field matching, durable event log, idempotency on MRN, separate env config, backoff on queries.
- Re-read the relevant sections of
references/finexus-api.md. - State remaining uncertainty: production host, hash field order for optional fields, enabled methods, settlement timing, test cards, and Kayaaku POS signing differences must be confirmed with Finexus.