Use this skill for GrabPay wallet and PayLater by Grab online checkout work (Grab Partner API, not in-store QR).
Source
Read references/grab-paylater-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, environments, both HMAC algorithms, the full One Time Charge flow with field tables, webhook payload, status inquiry, refunds, amount rules, rate limits, and token lifetimes.
Read references/grab-paylater-codes.md for every txStatus, reason code, redirect error value, 409 reason, OAuth error, and payment method enum.
Read references/grab-paylater-tokenisation.md only when the merchant needs saved-wallet, repeat, or subscription charges (Tokenised Payments v4: bind, charge, top-up, promo, unbind).
Read references/account-setup.md for sign-up, credentials, Integration Manager onboarding, plugins, Price Divider, branding rules, and settlement reports.
Read references/source-map.md to pick the right official page, and for doc coverage and known doc conflicts.
Core Workflow
- Confirm the merchant is onboarded: Grab issues
partner_id,partner_secret,client_id,client_secret,merchant_idand registers the redirect URL and webhook URL. There is no self-serve sandbox signup. - Pick the surface: plugin (Shopify, WooCommerce, Magento, EasyStore) or Direct API. For Direct API one-time checkout use OTC; for repeat charges use Tokenisation v4.
- Create a local pending order with a unique
partnerTxID(max 32 chars,[a-zA-Z0-9-_]), amount in sen, currencyMYR. - Server-side
POST /grabpay/partner/v2/charge/initsigned with partner HMAC (Authorization: {partner_id}:{signature}). Store the returnedrequest. - Build the GrabID authorize URL with PKCE (
S256),state,nonce,acr_values=consent_ctx:countryCode=MY,currency=MYR,request, scopeopenid payment.one_time_charge. Storecode_verifierandstateserver-side keyed to the order. - Redirect the shopper. On return, check
state; handleerrorvalues; takecode. - Server-side
POST /grabid/v1/oauth2/tokenwithcode,code_verifier,client_id,client_secret,redirect_uri,grant_type=authorization_code. Storeaccess_tokenencrypted (needed for complete, status, and refunds). POST /grabpay/partner/v2/charge/completewithAuthorization: Bearer {access_token}and a freshX-GID-AUX-POP. This step moves the money; without it the auth expires and Grab cancels and returns funds.- Mark paid only on final
txStatus: successfrom complete, status inquiry, or a verified webhook, after matchingpartnerTxID, amount, currency, and merchant. - Handle
processingby waiting for the webhook or polling status no more than once every 2 minutes. Refund with a new refundpartnerTxIDand the chargetxIDasoriginTxID.
Core Facts
- Production API base:
https://partner-api.grab.com. Staging base:https://partner-api.stg-myteksi.com. - Current OTC docs say test with Production test credentials and a test Grab account issued by the Integration Manager; staging URLs are still listed per endpoint.
- Partner HMAC string-to-sign:
METHOD\nContent-Type\nDate\nPATH[?QUERY]\nBASE64(SHA256(body))\n, HMAC-SHA256 keyed withpartner_secret, base64. X-GID-AUX-POP= base64url(JSON{"time_since_epoch":<unix>,"sig":base64url(HMAC-SHA256(client_secret, <unix> + access_token))}), no padding.Dateheader: RFC 7231 GMT, same value in header and signature; clock skew over 5 minutes causes 401.- Amounts are integers in the smallest unit: MYR 10.00 =
1000. - PayLater is not a separate API: it appears inside Grab checkout (
POSTPAID,INSTALMENT_4/8/12). Hide it withhidePaymentMethods: ["INSTALMENT","POSTPAID"]; the wallet cannot be hidden.metaInfois required for PayLater instalment transactions. - Lifetimes: request code 20 minutes, OAuth code 15 minutes, OTC access token about 1 year (
expires_in31535999). Uncompleted charges are cancelled and auto-refunded after 15 minutes; call complete within 10 minutes of the auth webhook or redirect. - Webhook:
Authorization: {partner_id}:{hmac}; when recomputing use Content-Typeapplication/json; charset=utf-8. UsetxStatus, not deprecatedstatus/newStatus. - Rate limit: max 50 API calls per second per Partner ID; back off with jitter on 429.
- Refund window Malaysia: 365 days. Merchant wallet is cashed out daily, so refunds can fail with
merchant_insufficient_balance. - Settlement reports: SFTP or Grab Merchant Portal (
https://merchant.grab.com/), delivered T+1 12:00, cut-off 23:59:59, CSV (pipe) or XLS.
Critical Rules
- Keep
partner_secret,client_secret, and access tokens server-side only; Grab says store secrets in a KMS, not config files, repos, or Redis. - Never mark paid from the redirect
codealone; the charge is only captured after/charge/completereturnssuccess. - Sign the exact body bytes you send; never re-serialise JSON between signing and sending.
- Generate a new
partnerTxIDfor every init and every refund; reuse returns the existing transaction ortransaction_already_exists. - Validate
stateon redirect andnonceinid_token; reject mismatches. - Treat any unknown reason code as non-final and re-query; only
successandfailedare final for charges. - Verify the webhook signature, then confirm with a status inquiry before fulfilment, because the webhook signing path is not spelled out in the docs.
- Do not test production with cURL or Postman (Grab security guidance); keep secrets out of shell history.
- Do not copy pricing; MDR is negotiated. Link to the Grab merchant page instead.
Completion Criteria
A GrabPay/PayLater integration is done only when:
- Charge init, token exchange, complete, status, and refund calls run server-side with correct HMAC or Bearer plus POP auth.
- PKCE verifier, state, and nonce are generated per order, stored server-side, and checked.
- Redirect handler covers
code, every documentederror, and missing or mismatchedstate. - Webhook handler verifies
Authorization, is idempotent perpartnerTxID+txType, and returns HTTP 200 fast. - Settlement checks
partnerTxID,txID, amount, currency,merchantID, finaltxStatus, and environment. processingand authorised-but-not-completed states are recovered by a job (status inquiry, then complete or mark failed).- Tests cover bad signature, clock skew, duplicate webhook, user cancel, session expiry, insufficient balance, partial refund, and refund
processing. - Deployment docs list
GRAB_PARTNER_ID,GRAB_PARTNER_SECRET,GRAB_CLIENT_ID,GRAB_CLIENT_SECRET,GRAB_MERCHANT_ID,GRAB_REDIRECT_URI, webhook URL, and base URL per environment.
Loophole Review Loop
When asked whether a Grab strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser redirect, GrabID authorize page, backend signer, token store, Grab Partner API, webhook receiver, raw-body parser, database, fulfilment job, refund job, settlement report.
- Check bypasses: forged redirect
code, replayedstate, missing PKCE check, paid-on-redirect without complete, re-serialised JSON breaking HMAC, wrong Content-Type in webhook HMAC, clock skew, staging/production credential mix, reusedpartnerTxID, auth expiry before complete, duplicate webhook, refund with wrongoriginTxID, refund while merchant wallet is empty, leaked access token. - Add fixes: server-only secrets, per-order PKCE/state/nonce, exact-bytes signing, NTP sync, idempotency keys, durable event log, recovery job using status inquiry, strict amount/currency/merchant checks, encrypted token storage.
- Re-read the relevant section of
references/grab-paylater-api.mdorreferences/grab-paylater-codes.mdfor any gap. - State remaining uncertainty: webhook signing path, GET body-hash convention, enabled payment methods, PayLater approval, Malaysian test accounts, and pricing all depend on Grab onboarding and the Integration Manager.