Use this skill for KineticPay (kineticpay.my) payment gateway integration work.
Source
Read references/kineticpay-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, the bill creation fields, the callback and requery flow, status codes, FPX bank codes, rate limits, errors, and the gaps in the official docs.
Read references/account-setup.md when the user asks how to register, where the merchant key or API key lives, how sandbox mode works, which env vars to use, payment method availability, settlement, or pricing.
Read references/source-map.md when choosing which official page or plugin file backs a fact, or to see what the public docs do not cover.
Core Workflow
- Identify environment: live or sandbox (sandbox is a toggle on the Collection page, same endpoints).
- Identify surface: custom server integration, WooCommerce, GiveWP, Gravity Forms, Forminator, WHMCS, or a no-code collection form/link.
- Confirm dashboard setup: approved company, a Collection with name and website URL, its merchant key, and (for API v2) the API key.
- Create a local pending payment with a unique
invoicestring before calling KineticPay. - Let the buyer pick an FPX bank; send its code as
bank. POST https://manage.kineticpay.my/payment/createserver-side withmerchant_key,invoice,amount,description,bank,callback_success,callback_error,callback_status.- Output the returned
html(an auto-submit form) to the browser to send the buyer to the bank. Onerror, show the messages. - On any callback hit, do not trust the request body. Requery
GET /payment/status?merchant_key=...&invoice=...server-side. - Settle idempotently only when the requery returns
code"00"and the invoice, amount, and local state match. - Keep a requery job for pending payments whose callback never arrived.
Core Facts
- Payment base (used by all official plugins):
https://manage.kineticpay.my. - Create bill:
POST /payment/create. Requery:GET /payment/status. - Bill auth is the Collection
merchant_keysent in the body (create) or query string (status). No header auth, no signature. - API v2 base:
https://manage.kineticpay.my/api/v2, authAuthorization: Bearer <API_KEY>, headersAcceptandContent-Type: application/json. - API v2 documented endpoints:
GET /ping,GET /bank,GET /company. Bills, Collections, Collection Forms, Transactions, Settlements and Points are listed in the docs nav but have no published page (checked 2026-10-21). - Successful payment code is
"00"(codeon requery,record.transaction_status_codeon the WooCommerce callback POST). amountis in ringgit with 2 decimals (for example"12.50"), not sen. MYR only.- FPX bank codes such as
MB2U0227,BCBB0235,PBB0233; fetch the live list fromGET /api/v2/bank. - Rate limit: 60 requests per minute per user;
X-RateLimit-Limit,X-RateLimit-Remainingheaders; HTTP 429 when exceeded. - Validation errors return JSON
{"error": {"field": ["message"]}}(observed with HTTP 200 on/payment/status). - Pagination on v2 list endpoints:
page,perPage(default 20, max 40), metadata inmeta.pagination. - Merchant key: Collection page, generated after you enter Collection name and website URL. API key:
https://manage.kineticpay.my/api-key.
Critical Rules
- Keep
merchant_keyand the API key server-side only. Never put them in browser code. - KineticPay documents no callback signature or checksum. Never mark paid from a callback body, redirect, or query string alone; always requery
/payment/statusserver-side. - The requery puts
merchant_keyin a URL query string. Do not log full requery URLs; redact them in HTTP client logs. - Make
invoiceunique per payment attempt and store it before redirecting. Official plugins use a site prefix plus order id plus a suffix (for exampleMYSHO123KNWC). - Compare requery
code, invoice, and amount against the local record. The status response schema is not documented; log the full response and confirm which amount field it returns. - Settle idempotently: the same invoice can hit
callback_success,callback_status, and a requery job. - Send
amountas a 2-decimal ringgit string. Do not send sen integers. - Treat the WooCommerce plugin's 3-second cron and the plugin defects listed in the API reference as patterns to avoid, not copy.
- Disable sandbox mode on the Collection before going live, and test once in live with a small amount.
- Card, e-wallet and BNPL are not exposed in any published API field; the public bill flow is FPX with a
bankcode.
Completion Criteria
A KineticPay integration is done only when:
- Bill creation runs server-side with
merchant_keyfrom env, and thehtmlresponse is rendered only after a local pending record exists. - The checkout collects a valid FPX
bankcode (fromGET /api/v2/bankor a vetted list). - All three callback URLs point to a server route that requeries
/payment/statusand never trusts the request body. - Settlement checks
code === "00", invoice, amount, MYR, and local status, inside an idempotent transaction. - A requery job reconciles pending payments within the rate limit (60/min).
- Tests cover: forged callback body with
"00", unknown invoice, amount mismatch, duplicate callbacks, failed code,errorresponse on create, 429 handling. - Deployment docs list
KINETICPAY_MERCHANT_KEY,KINETICPAY_API_KEY(if v2 is used), callback base URL, and the sandbox toggle state.
Loophole Review Loop
When asked whether a KineticPay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser, auto-submit form, FPX bank page, callback routes, backend bill creator, KineticPay
/payment/*, API v2, database, fulfilment job, requery job, dashboard Collection settings. - Check bypasses: forged callback POST with
transaction_status_code: "00", replayed callback, guessed invoice, invoice reuse across attempts, amount tampering before create, sandbox left on in production, merchant key leaked in logs or frontend, stale pending never requeried, rate limit exhaustion from aggressive polling, wrong Collection key for the site. - Add fixes: server-side requery as the only source of truth, unique unguessable invoice, amount check against local record, idempotent settle, redacted logs, backoff on 429, sandbox check at deploy.
- Re-read
references/kineticpay-api.mdsections relevant to any gap. - State remaining uncertainty: undocumented status response fields, undocumented callback payload, no refund or recurring API, card plan access, and whether
callback_statusis called server-to-server. Tell the user to confirm these with KineticPay support (support@kineticpay.my).