Use this skill for MOBY / MobyPay payment integration work.
Source
Read references/moby-api.md before giving factual API guidance or writing integration code. It holds environments, auth, the endpoint catalogue, hosted checkout and Direct API field tables, callback payload, the signature algorithm, status/detail requery, capture/void/refund, sandbox data, rate limits, errors, plugins, and the known conflicts between MOBY's sources.
Read references/moby-recurring.md for card tokens, token charges, charge status/refund, the subscription API, and dashboard Recurring Billing.
Read references/moby-pos.md for POS/kiosk TCP integration, IPP installment plans, and Visa plan cancel.
Read references/account-setup.md for onboarding, where credentials come from, sandbox vs live, dashboard features, env vars, settlement and pricing caveats.
Read references/source-map.md to pick the official page for a topic and to see coverage.
Core Workflow
- Identify environment: sandbox
https://dev.pay.mobycheckout.comor productionhttps://pay.mobycheckout.com. - Identify surface: hosted checkout (default), Direct API for one method, token/recurring, dashboard payment link or recurring billing, plugin, or POS/kiosk.
- Confirm credentials: Client ID and Secret Key for that environment, issued by
merchantsupport@moby.my; merchant category (insurance merchants must send NRIC). - Create a local pending payment with a unique
referenceNo, expected amount (MYR, 2 decimals), and environment before calling MOBY. - Get a Bearer token with
POST /api/auth/token; cache untilexpired_at, refresh on401. - Create the session server-side (
/api/merchant/payment/checkout/hostedreturnspayLink;/api/merchant/payment/direct/payreturnspayUrl) and redirect the customer. - Treat the
returnUrlredirect as UX only, even though it carries a signed query string. - On the
callbackUrlPOST, verifysignature(HMAC-SHA256, Secret Key, 8 fields in fixed order) before anything else. - Settle idempotently only when
statusissuccessandreferenceNo,amount, environment and merchant match; reply HTTP 200{"status":"success"}. - Requery with
/api/merchant/payment/detailor/statuswhen a callback is missing, late, or notsuccess.
Core Facts
- Token:
POST /api/auth/tokenwithclientId+secretKey; useAuthorization: Bearer <token>; docs say 30 minute lifetime. - Hosted checkout:
POST /api/merchant/payment/checkout/hosted, requiredclientId,customerName,referenceNo,details,amount; response{ success, payLink }. - Direct pay:
POST /api/merchant/payment/direct/paywithpayMethodfromPOST /api/merchant/payment/method/list; response{ success, payUrl }. - Amounts are MYR decimals (ringgit, not sen) on live v1 endpoints. The
/v2/...cents API is Coming Soon only. - Callback fields:
referenceNo,transactionId,amount,payMethod,status,time,merchantOrderRef,description,signature. - Signature: lowercase hex HMAC-SHA256 with the Secret Key over the concatenated values of
amount,description,merchantOrderRef,payMethod,referenceNo,status,time,transactionId(null becomes empty string, no separator). - Statuses: docs list
success,failed,pending; MOBY's plugins also handlecancelledandprocessing. - Requery:
POST /api/merchant/payment/status(clientId,referenceNo,transactionId) or/detail(clientId,referenceNo). - Refund
POST /api/merchant/payment/refund; voidPOST /api/merchant/payment/voidsame day only; capturePOST /api/merchant/payment/capture. - Recurring:
POST /api/v2/tokensreturns a save-cardredirect_url; charge withPOST /api/v2/tokens/{token}/charges(3dsrequired). - Rate limits: auth 10/min per client, general 60/min per token,
429withRetry-After. - Sandbox: Mastercard test cards, expiry drives result (
01/39approved); FPX only ACF Bank B2Buser1/password1; no e-wallet sandbox (real charges). - No webhook IP list, signature header, dashboard webhook registry, or public status page is documented.
Critical Rules
- Keep the Secret Key server-side. It mints tokens and is the callback HMAC key.
- Never mark paid from
returnUrl,payLink/payUrlcreation, a frontend message, or an unsigned payload. - Verify the signature over values exactly as received; do not reformat
amountortime; mapnullto""(JavaScriptString(null)is"null"). - Use constant-time comparison and reject on mismatch; log the raw payload instead of loosening the check.
- Do not put your own query params in
callbackUrl/returnUrlunless you strip them before hashing; also strip a leading?from keys MOBY may append. - Make
referenceNounique per attempt; hosted checkout returns no session ID, so it is your only correlation key. - Make callback handling idempotent; one
referenceNomay see several transactions and repeated callbacks. - Compare amounts as 2-decimal strings or integer sen, never floats.
- Do not test e-wallets casually in sandbox; they charge real money.
- Do not build on
/v2/..., Financing, Loyalty, or Merchant Management endpoints; they are not in production. - Where docs, OpenAPI and plugins disagree (listed in the references), confirm with MOBY Merchant Support before go-live.
Completion Criteria
A MOBY integration is done only when:
- Token, session creation and requery run server-side with environment-matched Client ID, Secret Key and base URL.
- A local pending payment with unique
referenceNoand expected amount exists before redirecting. - The callback handler verifies the HMAC over the documented 8 fields with the Secret Key, in constant time.
- Settlement checks
status === "success",referenceNo, amount, environment and merchant, and is idempotent. - The handler returns HTTP 200
{"status":"success"}only after durable processing. - Missing or non-final callbacks are reconciled through
/api/merchant/payment/detailor/status. - Refunds and voids are recorded as pending until a signed callback or status check confirms them.
- Tests cover valid signature, tampered field, null
merchantOrderRef, wrong amount, duplicate callback,failed/pending/cancelled, and a?-prefixed query key. - Deployment docs list
MOBY_CLIENT_ID,MOBY_SECRET_KEY, base URL, callback URL, return URL, and sandbox/live separation.
Loophole Review Loop
When asked whether a MOBY strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser return redirect, MOBY hosted page, backend session creator, token cache, MOBY API, callback receiver, body parser, database, fulfilment job, refund/void job, recurring charge scheduler, plugin, dashboard, POS/kiosk TCP link.
- Check bypasses: forged return URL, unsigned or tampered callback,
nullhashed as"null", reformatted amount, wrong Secret Key or environment, reusedreferenceNo, wrong amount, duplicate callback, callback before local record committed, expired token mid-flow, rate-limit storms from per-request auth, partial refund field guess, sandbox e-wallet charges, replayed kiosk message, default kiosk secret. - Add fixes: server-side session creation, pending record first, documented 8-field HMAC, constant-time compare, strict amount/reference checks, durable event log, idempotent settlement, token caching, status/detail requery, nonce and timestamp checks on TCP, environment-separated config.
- Re-read the relevant section of
references/moby-api.md,references/moby-recurring.mdorreferences/moby-pos.mdfor any gap. - State remaining uncertainty where it depends on MOBY confirmation: direct-pay callback delivery, partial refund field, callback retry policy, insurance NRIC field name, token charge
client_idplacement andcustom_datatype,x-tokenissuance, settlement timing, account method activation, and pricing.