Use this skill for OxPay (OxPay Financial / OxPay Malaysia) payment gateway integration work.
Source
Read references/oxpay-api.md before giving factual API guidance or writing integration code. It holds the endpoint catalogue, environments, required headers, the Signature (HMAC-SHA256) algorithm, full request/response field tables for hosted page, create payment, void, refund, queries, payouts, all webhooks, status codes, transaction states, brand enums and known doc gaps.
Read references/account-setup.md when the user asks how to become an OxPay merchant, where API keys and Sign Keys live, the merchant portal, MID/TID, go-live testing, payment method activation, settlement reports, pricing or support channels.
Read references/source-map.md to pick the right official page or to check docs coverage.
Core Workflow
- Confirm the merchant is onboarded and has MID (
merchant_id, max 9 chars) and TID (terminal_id, exactly 14 chars) from OxPay. - Choose surface: Hosted Payment Page (
POST /payment-page, terminal needs the Ecommerce feature) or merchant-hosted Create Payment (POST /payment, card data requires your own PCI DSS compliance). - Create a local pending order first, with a
merchant_reference_idunique per terminal (1 to 100 chars). - Serialize the request JSON once in compact form, sign it with HMAC-SHA256 using the Sign Key, send the same bytes with
Authorization: Bearer <API_KEY>,Signature: <hex>and aUser-Agentheader. - For hosted checkout, redirect the browser to
body.oxpay_hpp_url. For QR (MPQR) renderbody.qr_stringbeforepayment_expiry_time. - Treat
success_url/failure_urlas browser UX only. Do not fulfil from them. - Receive the payment webhook at
notification_url, verify theSignatureheader with the Sign Key, then parse. - Settle idempotently only when
headers.status_codeis0,body.transaction_stateissuccess(orcapturedfor pre-auth capture), andmerchant_reference_id,oxpay_txn_id, amount and currency match the local order. - If the webhook is late or missing, requery with
GET /payment/{oxpay_txn_id}orGET /payment?merchant_reference_id=.... - Refund with
POST /refund(successful sale) or void/cancel withPOST /void; final outcome comes via the refund or void webhook.
Core Facts
- Live base URL:
https://api.oxpayfinancial.com. Sandbox listed in the OpenAPI spec:https://api.uat.oxpayfinancial.com, but Getting Started says "no UAT environment available" and testing is done in production with OxPay test cases. Confirm with OxPay. - API version in spec: 2.0.2; optional header
OxPay-Version: 2.0.1. - Auth header:
Authorization: Bearer <API_KEY>(keys look likeak-...). - Integrity header:
Signature= lowercase hex HMAC-SHA256 of the compact JSON body (no whitespace between tokens, original key order) keyed with the Sign Key. Required on POST requests; sent by OxPay on every webhook. User-Agentheader is required on every request.- GET query endpoints and
GET /payouts/{unique_reference}take Authorization and User-Agent only (no Signature in spec). - Amounts are positive integers in the smallest currency unit (docs example: SGD 1 = 100). For MYR this means sen.
- Currency is ISO 4217 alpha-3. Public examples use SGD only; MYR support depends on your account.
headers.status_code: 0 Success, 1 Pending, 2 Rejected, 3 Error. Rejected/Error return HTTP 400.transaction_stateenum: success, requested, authorized, pending, rejected, error, expired, voided, refunded, captured, capture_submitted, capture_rejected.- Documented brands:
card,alipay,wechat pay,grabpay,shopeepay,atome,dash,PayNow,upi. FPX, DuitNow and Touch 'n Go are not in the public API docs (checked 2026-10-21). - Card
capture: falsemeans pre-auth. No capture endpoint is documented. - Merchant portal:
https://merchant.oxpayfinancial.com; loginhttps://login.oxpayfinancial.com/login. API keys: Configurations > API Keys > Add New Key. - Support:
support@oxpayfinancial.com,https://oxpay.freshdesk.com/support/home.
Critical Rules
- Keep the API key and Sign Key server-side only.
- Sign exactly the bytes you send. Do not pretty-print after signing or let an HTTP client re-serialize the body.
- Verify the webhook
Signaturebefore trusting any field; use a constant-time comparison. - Never mark paid from
success_url, a frontend callback, astatus_codeof 1, or a create-payment response alone (MPQR returns Pending). - Check amount, currency,
merchant_reference_id,oxpay_txn_id, MID/TID and state before settling. - Make webhook handling idempotent; key on
oxpay_txn_idplus transaction type. - Do not send raw card data to
/paymentunless the merchant is PCI DSS compliant; otherwise use the Hosted Payment Page. - Keep
merchant_reference_idunique per terminal and stable across retries. - Session IDs from
/payment-pageexpire; request a new one after expiry. - Webhook retry policy, source IPs, required HTTP response and rate limit numbers are not documented. Do not claim them.
- Confirm MYR, FPX, DuitNow, e-wallet and BNPL availability with OxPay before promising them.
Completion Criteria
An OxPay integration is done only when:
- Hosted page or create payment runs server-side with Bearer API key, Signature and User-Agent headers.
- The signed string and the sent body are byte-identical, tested with a known vector.
- Webhook handler verifies
Signaturewith the Sign Key before parsing and responds quickly. - Settlement checks status_code, transaction_state, reference IDs, amount, currency and terminal.
- Duplicate webhooks, late webhooks and requery are idempotent.
- Refund and void flows store
oxpay_original_txn_idand settle from their webhooks. - Tests cover bad signature, wrong amount/currency/reference, pending, rejected, expired, duplicate and success.
- Deployment docs list
OXPAY_API_KEY,OXPAY_SIGN_KEY,OXPAY_MERCHANT_ID,OXPAY_TERMINAL_ID,OXPAY_BASE_URL, notification URL and go-live test results.
Loophole Review Loop
When asked whether an OxPay strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser redirect, hosted page, merchant card form, backend signer, OxPay API, webhook receiver, JSON serializer, database, fulfilment, refund/void jobs, payout jobs, merchant portal.
- Check bypasses: fake success redirect, forged webhook, signature over re-ordered or pretty JSON, unicode escaping mismatch, wrong Sign Key, wrong amount/currency/reference, reused
merchant_reference_id, Pending treated as paid, expired QR or session, duplicate webhook, refund replay, pre-auth treated as captured, UAT/live confusion. - Add fixes: server-side signing, single serialization, constant-time compare, strict field checks, durable event log, idempotency keys, requery fallback, environment config separation.
- Re-read
references/oxpay-api.mdsections relevant to any gap. - State remaining uncertainty: sandbox availability, MYR and local method support, webhook retries and response contract, rate limits, capture flow, settlement timing and pricing.