Use this skill for SPayLater acceptance on a merchant's own website, app or store in Malaysia. SPayLater is accepted through ShopeePay's APIs; it is a payment method (spay_later), not a separate API. For Shopee marketplace sellers there is nothing to integrate.
Source
Read references/spaylater-api.md before giving factual API guidance or writing integration code. It holds hosts, auth and signature (with a verified test vector), the endpoint catalogue, Gateway v1 and Checkout v3 field tables, status, callbacks, refunds, invalidate/cancel, errcodes, and all enums including SPayLater payment channels.
Read references/spaylater-tokenized.md when the merchant wants to show SPayLater tenures on its own checkout (Link & Pay API-based), link ShopeePay accounts, charge recurring payments, or hold and capture.
Read references/spaylater-widget.md for "As low as RM X/mth" promotional messaging (Web, Android, iOS, Shopify) and branding rules.
Read references/account-setup.md for onboarding, credentials, env vars, sandbox, plugins, settlement, and pricing pointers.
Read references/source-map.md to pick the right official page, see coverage, and see the gaps only ShopeePay can answer.
Core Workflow
- Confirm the merchant has a signed ShopeePay agreement that includes SPayLater, plus Client ID, Secret Key,
merchant_ext_id,store_ext_idfor the environment. - Pick the surface: Payment Gateway v1 hosted checkout, Checkout with ShopeePay v3, Link & Pay API-based (own tenure picker), plugin (Shopify, WooCommerce), or in-person MPM/CPM.
- Pick the host pair for that surface and environment (wallet
api.uat.wallet.airpay.com.my/api.wallet.airpay.com.my, gatewayapi.gw.uat.airpay.com.my/api.gw.airpay.com.my). - Create a local pending payment with reference, expected amount x100, currency
MYR, environment. - Create the order server-side, signing the exact JSON string sent with HMAC-SHA256 + Base64 in
X-Airpay-Req-H. - Select SPayLater:
allowed_payment_method: ["spay_later"](v1),preferred_payment_method_type: "spay_later"(v3), orpayment_method_type: "spay_later"+ tenurepayment_option_reference(Link & Pay). - Redirect to
checkout_urlorredirect_url_http. Treat the return URL as UX only. - Verify each callback signature over the raw body, match reference, merchant, store, amount and currency, dedupe, settle, reply
{"errcode":0}. - Because Malaysian v3 callbacks are sent once with no retry, poll Check Transaction Status (or Get Checkout Status) on the documented schedule when no callback arrives, then invalidate or cancel.
- Refund through the API for the same surface; requery refund status.
Core Facts
- Malaysia region code
com.my. Wallet API productionhttps://api.wallet.airpay.com.my, staginghttps://api.uat.wallet.airpay.com.my. - Payment Gateway production
https://api.gw.airpay.com.my, sandboxhttps://api.gw.uat.airpay.com.my. - Headers:
X-Airpay-ClientId: <CLIENT_ID>,X-Airpay-Req-H: base64(hmac_sha256(secret, raw_body)). - Checkout v3:
POST /v3/merchant-host/order/create; MYvalidity_periodmax 3600 s, default 1200 s. - Gateway v1:
POST /v1/checkout,GET /v1/checkout/{checkout_id},POST /v1/checkout/cancel/{checkout_id},POST /v1/refund,GET /v1/refund/{refund_id}. - Status:
POST /v3/merchant-host/transaction/check(transaction_type13 payment, 15 refund);status3 = success. - Refund v3:
POST /v3/merchant-host/transaction/refund/create-new; partial refunds allowed; blocked 12 am to 5 am local by default. - Amounts are integers x100 (RM 12.34 =
1234). - SPayLater payment channels: 4 BNPL, 5 = 2M, 6 = 3M, 7 = 6M, 8 = 12M, 9 = 18M, 10 = 24M, 11 = 4M, 12 = 5M.
- MY v3 callback success:
payment_status1 (Checkout/MPM/CPM) ortransaction_status3 (Link & Pay/Subscription). - Gateway callback events:
checkout.successful,checkout.expired,checkout.cancelled,refund.successful,refund.failed. - Polling: every 5 s increasing to 100 s, then every 5 minutes up to 24 hours.
- SPayLater in Malaysia is provided by Monee Capital Malaysia Sdn. Bhd.; ShopeePay Malaysia is platform partner and payment facilitator.
- Settlement: daily T+1, weekly Monday, or monthly first day; payout up to 2 more days.
- Rate limits, callback IPs, SPayLater min/max amounts and public test users are not documented (checked 2026-10-21).
Critical Rules
- Keep the Secret Key server-side. Only the SPL widget Access Key may go to the browser.
- Sign and send the same serialized string; never re-serialize after signing.
- Verify callback signatures on the raw body with constant-time comparison before parsing.
- Never mark paid from the return URL or its query parameters.
- Confirm amount and reference against the original request before settling (ShopeePay requirement).
- Make callback handling idempotent; Gateway
event_idor reference +transaction_snas keys. - Do not rely on callbacks alone in Malaysia: they are not retried.
- Treat SPayLater CPM/Checkout "Processing" as pending, not failed.
- Compare Gateway status strings case-insensitively; accept
succeededandsuccessfulfor refunds. - Do not send
validity_periodandexpiry_timetogether. - Do not domain-whitelist or IP-restrict ShopeePay redirect URLs.
- Show only
is_available: trueSPayLater tenures and displaycompliance_notices. - Never show guaranteed-approval wording; follow the widget compliance rules.
- Do not quote merchant fees; they are set in the commercial agreement.
Completion Criteria
An SPayLater integration is done only when:
- Order creation runs server-side with correct host,
X-Airpay-ClientId, and a signature that matches the docs test vector in a unit test. - SPayLater is selected or offered per the chosen surface, and the agreement confirms SPayLater is enabled.
- Callback URL is registered with ShopeePay for the right environment.
- Callback handler verifies
X-Airpay-Req-Hover the raw body, checks reference, merchant, store, amount, currency, dedupes, and replieserrcode 0. - A poller covers missing callbacks with the documented schedule, then invalidates or cancels.
- Refunds (full and partial) and refund requery work and are idempotent.
- Tests cover bad signature, replayed callback, wrong amount/reference, processing then success, expired, cancelled, refund failure, and 12 am to 5 am refund block.
- Deployment docs list
SHOPEEPAY_CLIENT_ID,SHOPEEPAY_SECRET_KEY,SHOPEEPAY_MERCHANT_EXT_ID,SHOPEEPAY_STORE_EXT_ID,SHOPEEPAY_ENV, callback URL, return URL, and staging/production separation.
Loophole Review Loop
When asked whether an SPayLater strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser return URL, Shopee/ShopeePay app jump, hosted checkout page, merchant backend, ShopeePay wallet API, gateway API, callback receiver, raw-body parser, database, poller, refund job, widget script, plugin settings.
- Check bypasses: forged callback, signature over parsed JSON, wrong secret or environment, wrong host family, fake return URL params, wrong amount/currency/reference/store, duplicate callback, missed callback with no retry, SPayLater "Processing" treated as failure, expired order paid late, double refund, refund during block window, tenure option unavailable, widget shown where SPayLater is not live.
- Add fixes: server-side creation, local pending record, raw-body HMAC with constant-time compare, strict field matching, durable event log, idempotency keys, documented polling, invalidate/cancel on timeout, separate staging/production config, compliance review.
- Re-read the relevant sections of
references/spaylater-api.mdandreferences/spaylater-tokenized.md. - State remaining uncertainty from the gaps list in
references/source-map.md(GET signing, response signature header, Gateway callback ack, min/max amounts, refund window, product availability in Malaysia).