Use this skill for direct ShopeePay merchant API work (ShopeePay Malaysia Sdn Bhd), not for ShopeePay accepted through another aggregator gateway.
Source
Read references/shopeepay-gateway-api.md first for any factual API guidance or code. It holds hosts, headers, the signature algorithm with a verified test vector, the endpoint catalogue, Checkout with ShopeePay, MPM, CPM, invalidate, refund, Notify Transaction Status, Check Transaction Status, common enums, error codes, and the retry policy.
Read references/shopeepay-gateway-hosted-gateway.md for the separate ShopeePay Payment Gateway product (/v1/checkout, /v1/refund, webhook events) on the api.gw.* hosts.
Read references/shopeepay-gateway-tokenized.md for Account Linking, access tokens, Link & Pay, Subscription, Auth & Capture, and the risk additional_info object.
Read references/account-setup.md for onboarding, credentials, sandbox, plugins, callback URL registration, and Malaysia availability.
Read references/source-map.md to pick the right official page and to see doc coverage and known doc gaps.
Core Workflow
- Identify the product: Checkout with ShopeePay (online redirect), ShopeePay Payment Gateway (hosted multi-method checkout), MPM dynamic QR, CPM scan, Link & Pay, Subscription, or Auth & Capture.
- Identify environment and host: wallet APIs
api.uat.wallet.airpay.com.my(staging) /api.wallet.airpay.com.my(production); hosted gatewayapi.gw.uat.airpay.com.my/api.gw.airpay.com.my. - Create a local pending payment with a unique
payment_reference_idand the amount in sen (RM x 100) before calling ShopeePay. - Serialize the JSON body once, sign those exact bytes with HMAC-SHA256 using the secret key, Base64 encode, and send
X-Airpay-ClientIdandX-Airpay-Req-Hheaders. All wallet API calls are server-sidePOST. - Check
errcode(0 = success) in every response; treat-1,-2,5, timeouts, and "processing" as unknown, never as failed. - Redirect the customer to
redirect_url_http(Checkout) or showqr_content(MPM). Treatreturn_urlas UX only. - Verify the Notify Transaction Status callback signature over the raw body, match
payment_reference_idandamount, then reply{"errcode":0}. - In Malaysia the callback is sent only once, so always run Check Transaction Status as a fallback on the documented backoff schedule.
- Settle idempotently; invalidate abandoned orders or QRs; refund with a unique
refund_reference_id.
Core Facts
- Signature: Base64(HMAC-SHA256(secret_key, raw_request_body)) in header
X-Airpay-Req-H; client ID inX-Airpay-ClientId. - Protocol: HTTPS, POST, JSON, UTF-8, UNIX seconds, TLS 1.2 or 1.3, no SDK (direct REST only).
- Amount is an integer inflated by 100 (RM 10.00 =
1000). - Checkout with ShopeePay:
POST /v3/merchant-host/order/create, returnsredirect_url_http; Malaysia max validity 3600 s, default 1200 s. - MPM dynamic QR:
POST /v3/merchant-host/qr/create; Malaysia max 3600 s, default 1200 s;qr_urlvalid 5 minutes. - CPM:
POST /v3/merchant-host/transaction/payment/createwith the scannedpayment_code. - Status:
POST /v3/merchant-host/transaction/checkwithreference_id,transaction_type(13 payment, 15 refund) and originalamount. - Refund:
POST /v3/merchant-host/transaction/refund/create-new; full or partial; 365-day window; idempotent on identical payload. - Callback success (MY):
payment_status = 1(CPM/MPM/Checkout) ortransaction_status = 3(Link & Pay/Subscription). - Transaction status enum: 1 initial, 2 processing, 3 successful, 4 failed, 6 expired, 7 invalidated.
- Callback URL is registered with the ShopeePay integration team during onboarding, not per request.
- Credentials (Client ID, Secret Key,
merchant_ext_id,store_ext_id) are issued after NDA and commercial agreement; no self-serve sandbox.
Critical Rules
- Keep the secret key server-side; never sign in a browser or mobile app.
- Sign the exact byte string you send; do not re-serialize between signing and sending.
- Verify callback
X-Airpay-Req-Hover the raw body with constant-time comparison before parsing. - Do not mark paid from
return_url, frontend state, or a customer screenshot alone. - Validate
amountandpayment_reference_idagainst the original request before marking paid (docs require this). payment_methodin callbacks and status is the product flow (Point of Initiation), not a reliable validation value; docs say do not default-validate on it.- Do not whitelist domains or IPs for
redirect_url_http; ShopeePay says not to. - Use
request_idunique per call andpayment_reference_idunique per order; errcode 11 means duplicate request. - Partial refunds: wait for the previous one to finish; refunds are blocked by default 12am to 5am local time (errcode 601).
- Ignore unknown response fields and field order; ShopeePay adds fields without notice.
Completion Criteria
A ShopeePay integration is done only when:
- All calls run server-side with correct
X-Airpay-ClientIdandX-Airpay-Req-H, and the signature unit test passes the documented test vector. - The local order stores
payment_reference_id,request_id, amount in sen, currencyMYR, environment, and state before redirect or QR display. - The callback handler verifies the signature on the raw body, checks reference and amount, is idempotent, and returns
{"errcode":0}. - A requery job calls Check Transaction Status on the 5 s step backoff to 100 s, then every 5 minutes up to 24 hours.
- Abandoned orders call Invalidate Order (Checkout) or Invalidate QR (MPM).
- Refunds use unique
refund_reference_id, handle errcode 5 and 320, and are re-checked withtransaction_type15. - Tests cover bad signature, wrong amount, duplicate callback, errcode -1/5/timeout, expired order, and refund failure.
- Config documents
SHOPEEPAY_CLIENT_ID,SHOPEEPAY_SECRET_KEY,SHOPEEPAY_MERCHANT_EXT_ID,SHOPEEPAY_STORE_EXT_ID,SHOPEEPAY_ENV, and the callback URL registered with ShopeePay.
Loophole Review Loop
When asked whether a ShopeePay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser, ShopeePay app or web page,
return_url, backend signer, ShopeePay API, callback receiver, raw-body parser, database, requery job, refund job, plugin settings. - Check bypasses: forged callback, signature over re-encoded JSON, wrong secret or host (UAT vs production, wallet vs
gw), amount in ringgit instead of sen, reusedpayment_reference_id, errcode -1 treated as failed, missed single-shot MY callback, expired order paid late, duplicate refund, refund in block window, stale access token, unlinked account still charged. - Add fixes: server-only signing, raw-body HMAC, constant-time compare, strict reference/amount match, unique ids, durable callback log, requery backoff, invalidate on cancel, idempotent settlement and refund records.
- Re-read the relevant reference sections for any gap.
- State remaining uncertainty: response signature header name, callback IP ranges, sandbox test data, rate limits, hosted gateway method availability, and pricing are not published; confirm with the ShopeePay integration team.