Use this skill for Paydibs payment gateway integration work (Merchant Integration API v3, docs version 4.0 dated 24 Sep 2026).
Source
Read references/paydibs-api.md before giving factual API guidance or writing integration code. It contains source URLs, environments, the PAY request field table, response and callback fields, every Sign formula with verified examples, PTxnStatus codes, QUERY, REFUND, Hosted Payment Session, recurring, and documented gaps.
Read references/account-setup.md when the user asks how to register, which credentials are needed, where the Merchant ID and Merchant Password come from, staging vs production, env var names, payment method activation, settlement, or pricing.
Read the companion files for their areas: references/paydibs-codes.md (all enums and error codes), references/paydibs-recurring.md (CIT, billing rules, MIT), references/paydibs-hosted-session.md (card SDK), references/paydibs-tokens-instore.md (BINDOPT, REVOKE, DuitNow QR), references/paydibs-emandate.md (E-Mandate and Direct Debit). The Endpoint Catalogue in paydibs-api.md lists every documented operation.
Read references/source-map.md when choosing which Paydibs docs page applies to payment, response, query, refund, sign hashing, hosted session, recurring, tokens, e-mandate, or in-store QR.
Core Workflow
- Identify environment: staging (test account) or production. Both URLs come from Paydibs with the account.
- Identify integration surface: hosted checkout (PAY form post), Hosted Payment Session card SDK, recurring CIT/MIT, saved card token, or in-store DuitNow QR.
- Confirm credentials from Paydibs: Merchant ID (6 chars), Merchant Password (hash secret), and the payment URL host.
- Create a local pending payment with a unique
MerchantPymtID(max 20) before building the PAY request. - Build the PAY request server-side, computing
Sign= SHA512 hex of the documented field concatenation with Merchant Password first. - Auto-submit an HTML form (POST) from the browser to
<payment URL>/PPG/trigger. Never expose Merchant Password to the browser. - Treat the
MerchantRURLPOST as browser UX only; verify itsSignbut settle from the server callback or QUERY. - Handle
MerchantCallbackURL: parse the urlencoded body (it carries a JSON string), verifySign, check fields, return HTTP 200. - Settle idempotently only after
Sign,MerchantID,MerchantPymtID,MerchantTxnAmt,MerchantCurrCode, andPTxnStatus = 0match. - Use
TxnType=QUERYto/PPG/triggeras fallback when the callback is missing or status is pending (2).
Core Facts
- Payment, query, MIT, bind and revoke endpoint path:
/PPG/trigger. Refund:/PPG/refund. Hosted session:/PPG/create-pay-session. In-store QR:/PPG/offline/trigger-qr. E-Mandate:/PPG/trigger-emandate; Direct Debit:/PPG/create-ddi,/PPG/create-ddi-txn,/PPG/cancel-ddi. - No void, capture, partial refund, settlement report or payout API is published.
- Host: "URL provided by Paydibs". The official Hosted Session SDK hardcodes
https://stgapi.paydibs.com(stg) andhttps://v3api.paydibs.com(prod). TxnTypevalues (uppercase):PAY,QUERY,REFUND,REVOKE,BINDOPT,MIT.- Sign algorithm: SHA512, hexadecimal string, 128 chars. Plain concatenation, no separators, Merchant Password first.
- PAY Sign:
MerchantPassword + TxnType + MerchantID + MerchantPymtID + MerchantOrdID + MerchantRURL + MerchantTxnAmt + MerchantCurrCode + CustIP + PageTimeout + MerchantCallbackURL + Token(absent optional fields = empty string). - Response/Query Sign:
MerchantPassword + MerchantID + MerchantPymtID + PTxnID + MerchantOrdID + MerchantTxnAmt + MerchantCurrCode + PTxnStatus + AuthCode. - Amount: ringgit with exactly 2 decimals, no thousands separator (
1000.00, not1000or1,000.00). - PTxnStatus:
0success,1failed,2pending,9voided,10refunded,17/18cancelled,19expired,20chargeback,22bank maintenance,50/51amount limit,-1not found,-2internal error. - Callback: content type
application/x-www-form-urlencoded, body is a JSON string; retried up to 5 times until HTTP 200. - QUERY
PAYExists:0exists,1does not exist,2error, retry. Note0means found. - Method codes:
OBonline banking,CCcard,WAe-wallet. Currencies include MYR, SGD, PHP, VND, CNY, HKD, IDR, KHR, KRW, THB. - Production allows TLS 1.2 only; test TLS 1.2 against production before go-live.
- Replace
&with;insideMerchantRURLandMerchantCallbackURLquery strings.
Critical Rules
- Keep Merchant Password server-side only; it is the hash secret.
- Do not mark paid from the
MerchantRURLredirect alone, even with a valid Sign; prefer callback or QUERY. - Recompute Sign over the exact received field values and compare in constant time (case-insensitive hex).
- Reject callbacks whose
MerchantID, amount, currency, orMerchantPymtIDdiffer from the stored pending payment. MerchantPymtIDmust be unique per attempt; reuseMerchantOrdIDacross retries of one order.- Return HTTP 200 only after the callback is durably recorded; make processing idempotent across the 5 retries.
- Treat status
2(pending) as not final; requery later. Do not fail it early. - Use the Merchant ID, Password and host of the same environment; never mix staging and production.
- Refund response
RefundResultis boolean; Paydibs sample shows refunds only allowed from the next day onwards. - Verify payment method availability, fees, settlement and TLS in production with Paydibs before claiming production certainty.
Completion Criteria
A Paydibs integration is done only when:
- PAY request and Sign are built server-side and posted to
/PPG/triggervia auto-submit form. MerchantRURLhandler verifies Sign and only shows status; it does not fulfil on its own.MerchantCallbackURLhandler parses the JSON string body, verifies Sign, checks fields, returns HTTP 200, and is idempotent.- QUERY fallback runs for missing callbacks and pending (
2) payments. - Settlement checks MerchantID, MerchantPymtID, amount, currency, and
PTxnStatus = 0. - Tests cover a bad Sign, a duplicate callback, wrong amount/currency/ID, pending then success, failed/cancelled/expired, and a successful payment.
- Deployment docs list
PAYDIBS_MERCHANT_ID,PAYDIBS_MERCHANT_PASSWORD,PAYDIBS_BASE_URL, return URL, callback URL, and staging/production separation.
Loophole Review Loop
When asked whether a Paydibs strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser form post, Paydibs payment page, MerchantRURL handler, callback receiver, QUERY client, database, fulfilment job, refund job, hosted session SDK iframe, and Paydibs account settings.
- Check bypasses: forged RURL post, forged callback, Sign over wrong field order, null vs empty AuthCode, Password leaked to frontend, staging/live mix, wrong amount format, reused MerchantPymtID, duplicate callback, retry after partial processing, pending treated as failed,
PAYExists=0misread as missing, duplicate refund, and&in return URLs. - Add fixes: server-side Sign, local pending payment first, constant-time Sign check, strict field checks, durable event log, idempotency keys, environment-scoped config, QUERY fallback, and refund state tracking.
- Re-read
references/paydibs-api.mdsections relevant to any gap. - State remaining uncertainty where docs are silent: base URLs (provided by Paydibs), test cards/banks, IP allowlists, rate limits, refund windows, and null-field handling in Sign.