Use this skill for Kiple (kiplePay) payment gateway integration work.
Source
Read references/kiple-api.md before giving factual API guidance or writing integration code. It contains environments, the endpoint catalogue, hosted form fields, amount rules, return and callback fields, return codes, the SHA-1 hash formulas with a worked example, the enquiry API, recurring and split-order fields, and the legacy iOS SDK.
Read references/account-setup.md when the user asks how to register, which credentials are needed, plugin settings, UAT vs live, payment method activation, settlement, refunds, or pricing.
Read references/source-map.md to find the exact official plugin file behind a fact, or to see what is not covered.
Kiple has no public API docs. Facts here come from Kiple's own official plugins (GitHub org m2c, "Kiplepay Sdn Bhd") and live gateway responses. Say so when you answer, and tell the user to confirm anything marked "Not documented" with Kiple.
Core Workflow
- Identify environment: UAT (
uat.kiplepay.com) or production (kiplepay.com). - Identify surface: hosted form (one-off), recurring card payment, split order, or a platform plugin.
- Confirm credentials: Merchant ID and Secret Key for that environment, MYR store currency.
- Create a local pending payment with a unique
ord_mercrefand the exact amount string (two decimals) before building the form. - Build the form server-side: required fields plus
version=2.0,ord_returnURL,dynamic_callback_url, andmerchant_hashvalue = sha1(secret + ord_mercID + ord_mercref + amountDigits). - Auto-submit the form by POST to
/wcgatewayinit.php. - On the server callback (
nbcbpresent) and on the browser return, recomputeord_key = sha1(secret + merchantId + ord_mercref + amountDigits + returncode)from stored values and compare in constant time. - Before marking paid, call the enquiry URL and require body
S. - Settle idempotently on
returncode=100, matching reference, amount, merchant ID and a not-yet-seenwcID. - Treat the browser return as UX; if the callback never arrives, requery by enquiry.
Core Facts
- Payment entry: UAT
https://uat.kiplepay.com/wcgatewayinit.php, livehttps://kiplepay.com/wcgatewayinit.php(PHP SDK uses/gatewayon the same hosts). - Enquiry:
GET /enquiry.phpor/enquirieswithord_mercID,ord_mercref,ord_totalamt; plain-textS,F,A,Invalid Parameters,Records not Found. - Hash algorithm: SHA-1 lowercase hex over plain concatenation, secret first, no separators.
amountDigitsis the postedord_totalamtwith.and,removed (50.00becomes5000); split orders also remove|.- Minimum amount RM1.00; return URL must be fully qualified (gateway validation page).
returncode:100success,E1failed,E2aborted/timeout,-1invalid merchant request.- Response includes
wcID(Kiple transaction ID),ord_key,ord_mercref,ord_totalamt,payment_type,entry_id,error_description. - Server-to-server callback goes to
dynamic_callback_urland carriesnbcb. ord_dateformatY-m-d H:i:s;versionis2.0.- Currency MYR only (all official plugins).
- Recurring: card only (
payment_code=CC),ord_recurring_enable=1, monthly/quarterly/yearly, needs a Kiple recurring subscription; cancellation in Kiple's portal. - Split orders: pipe-separated
ord_mercIDandord_totalamt,ord_mmercIDmaster, hash with master secret. - No refund, void, capture or payout API in any official source.
Critical Rules
- Keep the Secret Key server-side; never put it in client JS or the form.
- Never fulfil from the browser return alone; verify
ord_keyand requery. - Recompute the response hash from your stored merchant ID, reference and amount, not from posted values.
- Format amounts to exactly two decimals, no thousands separators, and hash the same string you post.
- Use a fresh
ord_mercrefper attempt and map it back to your order (plugins appenduniqid). - Dedupe on
wcID; return and callback can both arrive for one payment. - Use the UAT secret with UAT hosts and the live secret with live hosts.
- On
E1/E2callbacks the official WooCommerce plugin sets orders on-hold, not failed; requery before final cancellation. - The WooCommerce "Verify Key" help text says "Just enter any value"; ignore it, the value must be the Secret Key.
- Set session cookies
SameSite=None; Secureif the return handler needs the buyer session. - Do not invent refund, webhook retry, or method-code behaviour; mark it Not documented and ask Kiple.
Completion Criteria
A Kiple integration is done only when:
- The form is built server-side with
version=2.0, two-decimal amount, uniqueord_mercref, and correctmerchant_hashvalue. ord_returnURLanddynamic_callback_urlare absolute HTTPS URLs for the right environment.- Both handlers verify
ord_keywith constant-time comparison against stored values. - Settlement requires
returncode=100, a valid hash, an enquiry resultS, and matching amount, reference and merchant ID. - Processing is idempotent on
wcIDand local payment state. - Tests cover bad hash, wrong amount, wrong reference,
E1,E2,-1, duplicate callback, missing callback with enquiry fallback, and success. - Deployment docs list
KIPLE_MERCHANT_ID,KIPLE_SECRET_KEY,KIPLE_ENV, return and callback URLs, and UAT/live separation.
Loophole Review Loop
When asked whether a Kiple strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser form, Kiple hosted page, return handler, callback handler, enquiry call, database, fulfilment job, recurring callback, Kiple portal.
- Check bypasses: forged return POST, hash over posted values, amount format mismatch (
50vs50.00), reusedord_mercref, UAT secret in production, legacywebcash.com.myhost mismatch, duplicatewcID, unsigned recurring callback, enquiry spoofing via DNS or HTTP, split order using sub-merchant secret. - Add fixes: stored-value hash check, constant-time compare, enquiry before fulfil over HTTPS, unique references,
wcIDunique index, environment-bound config, durable callback log. - Re-read
references/kiple-api.mdsections relevant to any gap. - State remaining uncertainty: callback acknowledgement format, retry policy, recurring callback signing, refunds, method codes, and anything in Kiple's private API document. These need confirmation from Kiple.