Use this skill for work against PayNet's own rails. PayNet is national payment infrastructure, not a merchant gateway. Most merchants reach FPX and DuitNow through a bank acquirer or a licensed payment gateway, and should use that provider's skill instead.
Source
Read references/paynet-api.md first. It is the entry point: who may integrate which product, environments and hosts, auth and signature per product, the full endpoint catalogue, and links to the detail files.
Read the detail file for the product in scope:
references/paynet-fpx.mdfor FPX merchant or TPA integration (B2C, B2B1, B2B2, bulk refund, AE status enquiry, bank list, checksum, certificates, UAT banks).references/paynet-duitnow-pay.mdfor DuitNow Pay acquirer APIs (hosted and self-hosted checkout, saved payment method, AutoDebit, refunds, webhooks, JWT auth).references/paynet-rpp-v3.mdfor RPP DuitNow v3 participant APIs (JWS, credit transfer webhook, refund intent, DuitNow Request, Reversal, AutoDebit, Consent, QR webhooks, network administration).references/paynet-duitnow-qr.mdfor building or parsing a DuitNow QR string and the acquirer QR flow.references/paynet-codes.mdfor every status, reason, reject and response code.references/account-setup.mdfor Developer Portal registration, project roles, certification, go-live, and merchant registration.references/source-map.mdto pick the official page for a question and to see coverage.
Core Workflow
- Identify the caller's role. Merchant, acquirer (bank or non-bank RPP participant), TPA for FPX, or issuer. If the user is a normal merchant, say they need an acquirer or gateway and stop unless they are an approved FPX merchant or TPA.
- Identify the product: FPX, DuitNow Pay, DuitNow Online Banking/Wallets v3, DuitNow Request, AutoDebit/Consent, Reversal, or DuitNow QR.
- Identify the environment: UAT (Certification Centre simulator or System Verification) or production.
- Create a local pending payment with your own unique ID (
fpx_sellerOrderNo/fpx_sellerExOrderNofor FPX,checkoutIdUUID v4 for DuitNow Pay,businessMessageIdfor v3) before calling PayNet. - Sign every request with the product's method (FPX RSA-SHA1 checksum, DuitNow Pay JWT RS256, v3 JWS with
dsdigest). Keep private keys server-side. - Redirect the payer in the documented way (FPX full-window form POST; DuitNow bank URL with
EndtoEndId,EndtoEndIdSignature,DbtrAgt). - Treat the browser return as UX only. Settle from the verified server-to-server message: FPX direct AC (reply
OK), DuitNow PayUpdate Payment Statuswebhook, or v3 webhook. - Requery when the server message is missing: FPX AE, DuitNow Pay
GET /v2/bw/checkout-status, v3POST /v3/transactions/enquire. Respect rate limits. - Settle idempotently on the documented final state only (FPX
fpx_debitAuthCode00; DuitNow Pay substateCLEARED).
Core Facts
- New docs:
https://docs.paynet.my. Old docshttps://docs.developer.paynet.mysay they are no longer updated. - Developer Portal:
https://developer.paynet.my, sign-up throughhttps://account.paynet.my. New companies must be verified by PayNet (ask@paynet.my) before go-live. - DuitNow Pay merchants "need to be affiliated with our merchant acquirers' network". Acquirers must already be RPP participants with Online Banking/Wallets, Consent and AutoDebit enabled.
- FPX UAT: AR
https://uat.mepsfpx.com.my/FPXMain/seller2DReceiver.jsp, AE.../sellerNVPTxnStatus.jsp, BE.../RetrieveBankList. Production FPX endpoint URLs are not in the public docs. - FPX checksum: RSA with SHA-1 over pipe-joined values in field-name order, hex uppercase, sent as
fpx_checkSum. - FPX status:
00success,99pending authorisation (B2B),09pending, anything else failed. Direct AC must be answered withOKor FPX resends. - DuitNow Pay auth:
AuthorizationJWT RS256 with claimsexp(within 1 hour),iss(BIC),sub(Merchant ID),jti(UUID v4),key(Project ID),data(request body). HeadersX-Ip-AddressandX-Gps-Coordinatesare required (0if unknown). - DuitNow Pay API base host is not documented publicly. The sample
redirectUrlhost ishttps://duitnow-pay.uat.inet.paynet.my:8443. - DuitNow Pay status polling: once per 30 seconds per transaction; final enquiry after 60 minutes; corporate flow enquiry on day 5. Refunds within 90 days.
- RPP v3 JWS: header
alg/typ/kid, claimsiss,iat,exp(within 1 hour),key,jti(= businessMessageId),ds(SHA-256 hex of the minified body). The text says RS512; the official code samples use RS256. - DuitNow QR: EMV TLV, ID
00first, CRC63last, CRC-16/CCITT polynomial1021initFFFF, AIDA0000006150001, currency458, countryMY. - All PayNet APIs require TLS 1.2. Rate-limited calls return 429
Quota has been exceeded. PayNet strongly discourages sandbox load tests.
Critical Rules
- Never tell a normal merchant they can sign up with PayNet for card or FPX acceptance. Route them to an acquirer or gateway.
- Never mark paid from the browser redirect, the indirect AC alone,
redirectUrlreturn, or a QR display. - For FPX, verify
fpx_checkSumon every AC with the current FPX certificate, then the old one, and reject on failure. - For FPX, do not whitelist FPX IPs, do not hardcode min/max limits, never use an iframe or pop-up, and show the FPX logo, operating hours and T&C link.
- For DuitNow Pay, settle on
paymentStatus.substate=CLEARED, not oncode(the docs' success samples showACTC/U002). - For v3, verify the response JWS signature with PayNet's certificate (
kid= serial) and recomputedsover the received body. - Use
possibleDuplicate/PssblDplct= true only for a repeat of the same request; never send a new ID for a retry. - Do not copy private keys from PayNet sample zips. Generate your own 2048-bit RSA key.
- Do not copy
CURLOPT_SSL_VERIFYPEER falsefrom the FPX PHP sample. Verify TLS. - Many v3 specs say "beta" or "specification review". Confirm availability with
commercial@paynet.mybefore building.
Completion Criteria
A PayNet integration is done only when:
- The caller's participant role and product are confirmed and the account is approved in the Developer Portal.
- Requests are signed server-side with the correct method, and keys and certificates load from secret storage.
- The server-to-server result (FPX direct AC, DuitNow Pay webhook, v3 webhook) is verified, acknowledged, and stored before fulfilment.
- Settlement checks own order ID, amount, currency MYR, status code, and environment.
- Missing callbacks are handled by the documented enquiry with the documented timing and rate limit.
- Duplicate callbacks, repeats, SAF resends and late corporate approvals are idempotent.
- Certification Centre and System Verification test cases are passed.
- Tests cover bad signature, wrong amount, duplicate callback, pending
09/99orPENDAUTH, rejected status, and success.
Loophole Review Loop
When asked whether a PayNet strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser, merchant server, acquirer server, PayNet API gateway, FPX, issuer bank, webhook receiver, key store, certificate files, database, fulfilment job, refund job, Developer Portal settings.
- Check bypasses: forged indirect AC, unsigned or wrongly ordered checksum, expired FPX certificate, old certificate not tried, JWT reused after expiry,
dsnot checked, webhook from unknown IP, wrong environment host, wrong amount, duplicatefpx_sellerExOrderNo, polling faster than 30 seconds, corporate approval after 5 days, refund over 90 days, SAF repeat processed twice. - Add fixes: server-side signing, full checksum verification with certificate rollover, JWS and
dsverification, IP allowlist plus signature checks, strict amount and ID matching, durable message log, idempotency keys, environment-specific config, scheduled requery. - Re-read the relevant section of the reference files for any gap.
- State remaining uncertainty where it depends on PayNet onboarding (hosts, IPs, credentials, certificates, product approval) or undocumented production details.