Use this skill for CommercePay (payments.commerce.asia) payment gateway integration work.
Source
Read references/commercepay-api.md before giving factual API guidance or writing integration code. It holds environments, auth, headers, the exact cap-signature algorithm with verified test vectors, the endpoint catalogue, request/response field tables, callback verification, status enums, refunds, saved payments, recurring, payouts, wallets, and error codes.
Read references/commercepay-codes.md when you need channelId values, FPX/DuitNow providerChannelId bank codes, payout bank codes, DuitNow Proxy codes, or staging payout test accounts.
Read references/account-setup.md when the user asks how to register, which credentials are issued, back-office location, staging vs production, env var names, recurring/payout enablement, plugins, settlement, or pricing.
Read references/source-map.md to pick the right official page for a topic.
Core Workflow
- Identify environment: staging (
https://staging-payments.commerce.asia/) or production (https://payments.commerce.asia/). - Identify surface: Direct Integration (merchant renders channels), Hosted Session Checkout (CommercePay page), recurring, saved payment, pre-auth, refund, or payout.
- Confirm the four credentials for that environment: Merchant Id, Username, Password, Secret Key.
- Call
POST /api/TokenAuth/Authenticate(headerAbp-TenantId, no signature) and cache theaccessTokenfor up to 24 hours. - Create a local pending payment with your unique
referenceCodeand expected amount in sen before calling CommercePay. - Sign every other request: lowercase(full URL + recursively key-sorted, minified, null-free camelCase JSON) then HMAC-SHA256 hex with the Secret Key into
cap-signature. - Call
RequestPayment(Direct) orInitialSession(Hosted) server-side with acallbackUrl; storetransactionNumberorsessionNumber. - Send the browser to
result.redirectUrl(or runclientScriptwhenredirectionTypeis2). - Treat
returnUrlas UX only. Verify the callbackcap-signature(computed with YOURcallbackUrlas the prefix), answer HTTP 200, then confirm withGET Query. - Settle idempotently when status is
1(Success) andreferenceCode,transactionNumber, amount, currency and environment match.
Core Facts
- Base URLs: staging
https://staging-payments.commerce.asia/, productionhttps://payments.commerce.asia/. - Every API call except Authenticate needs
Content-Type: application/json,Authorization: Bearer <accessToken>,Abp-TenantId: <MERCHANT_ID>,cap-signature. - Token:
POST /api/TokenAuth/AuthenticatebodyuserNameOrEmailAddress,password; returnsaccessToken,expireInSeconds86400. - Payment:
POST /api/services/app/PaymentGateway/RequestPayment. Hosted session:POST /api/services/app/PaymentGateway/InitialSession. - Status:
GET /api/services/app/PaymentGateway/Query?TransactionNumber=...&Timestamp=...(orSessionNumber). - Refund:
POST .../PaymentGateway/RefundPayment; refund status:GET .../PaymentGateway/QueryRefund. - Amounts are integers in minor units:
1000= MYR 10.00. timestampis Unix epoch milliseconds (new Date().getTime()), required on signed bodies.- Responses use an ABP envelope:
{ result, targetUrl, success, error: { code, message }, unAuthorizedRequest, __abp }. - Callback is a POST to
callbackUrlwithamount,channelId,currencyCode,referenceCode,status,transactionNumber,providerTransactionNumber(+paymentSessionNumberfor sessions), signed incap-signature. - Payment status
0Pending,1Success,2Failed,3Cancelled,8UserCancelled,9Authorized,10TransactionExpired,11Refunded (full table in api reference). - No
callbackUrlmeans no callback; you must poll Query Payment. - Payout uses the same
RequestPaymentendpoint with payoutchannelId(staging15, production9) and a funded payout wallet. - Channel IDs differ between staging and production (for example TNG is
10in staging,7in production). - Signature Validator Tool (staging back office):
https://staging-backoffice-payments.commerce.asia/app/paymentgateway/signaturevalidator.
Critical Rules
- Keep Password, Secret Key and access token server-side only.
- Do not mark paid from
returnUrl, browser query strings, or frontend state. - Verify callback
cap-signaturewith constant-time comparison before trusting any field. - Sign with raw UTF-8 (no
\uXXXXescapes), only JSON-required escaping (+ < > & 'stay literal), Unicode-aware lowercase. - Omit null fields at every nesting level before signing; keep empty strings.
- For GET, sign the URL without the query string plus the query params as sorted JSON, numbers unquoted.
- Use the Secret Key, channel IDs, and callback URL of the same environment.
- Pass
providerChannelIdonly when the channel hasisProviderHostChannel: true; otherwise omit it. - Keep
referenceCodeunique per payment attempt (max 50) and the callback handler idempotent. - Refunds only on
Successtransactions; omitamountfor full refund;reasonis required; cross-border refunds are not supported. - Recurring (Credit Card, TNG only) and payouts require Business Development approval first.
Completion Criteria
A CommercePay integration is done only when:
- Token is fetched server-side, cached, and refreshed on expiry or auth failure.
- All signed requests pass in staging (use the Signature Validator Tool when debugging).
RequestPaymentorInitialSessionruns server-side withcallbackUrl, and the returned id is stored before redirect.- Callback handler verifies
cap-signature, returns HTTP 200, and requeriesQuerybefore settling. - Settlement checks
referenceCode,transactionNumber/paymentSessionNumber, amount, currency, status1, and environment. - Duplicate callbacks, missing callbacks (Query polling fallback), and expired/failed statuses are handled idempotently.
- Tests cover invalid signature, null-field and non-ASCII signing, duplicate callback, wrong amount/reference, and status
0,2,8,10. - Deployment docs list
COMMERCEPAY_MERCHANT_ID,COMMERCEPAY_USERNAME,COMMERCEPAY_PASSWORD,COMMERCEPAY_SECRET_KEY,COMMERCEPAY_BASE_URL, callback and return URLs per environment.
Loophole Review Loop
When asked whether a CommercePay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser return, hosted session page, provider page, backend payment creator, token cache, CommercePay API, callback receiver, database, fulfilment, refund job, payout job, wallet balance, back office.
- Check bypasses: forged return URL, forged callback, signature over the wrong URL (request path instead of your
callbackUrl), escaped Unicode, nulls left in, unsorted nested keys, staging/production key or channel mix, expired token, reusedreferenceCode, wrong amount unit, session with several attempts, refund double-submit, payout to unregistered DuitNow proxy. - Add fixes: server-side creation, local pending record first, canonical signing helper with the published test vectors, constant-time compare, strict field matching, Query requery, durable event log, idempotency keys, per-environment config.
- Re-read
references/commercepay-api.mdsections relevant to any gap. - State remaining uncertainty: callback retry schedule, IP allowlist, timestamp tolerance, return URL parameters, and rate limits are not documented in official docs (checked 2026-10-21).