Opay Developer Platformv1.0.0 Beta

REST API for independent stores and WooCommerce backends — ledger, Connect, and payment links via opay.com.hk.

Authentication

All server-side requests must include your merchant plugin secret key in an HTTP header. Generate the key in Merchant Center → Settings after you register and complete KYC.

Never expose opay_sk_* keys in browser JavaScript or mobile apps.
X-Opay-Api-Key: opay_sk_live_…

X-Opay-Portal-Key (same value, accepted alias)

Tenant isolation

Each opay_sk_* key is bound to exactly one merchant UUID. If the key does not match {merchant_id} in the URL, the API returns 403 Forbidden with code TENANT_MISMATCH.

Base URL

https://www.opay.com.hk

Paths are prefixed with /api/merchants/{merchant_id}/…

Quickstart (5 minutes)

  1. Register at /login and complete compliance onboarding (KYC)
  2. Merchant Center → Settings → Generate API key (opay_sk_…) and copy Merchant ID
  3. Call GET /api/merchants/{id}/overview from your server with X-Opay-Api-Key
  4. Read opay_balance.spendable_balance for Visa card spend eligibility

Core endpoints

MethodPathDescription
GET/api/merchants/{merchant_id}/overviewLedger buckets + spendable balance + risk tier
GET/api/merchants/{merchant_id}/balanceRaw balances table row
GET/api/merchants/{merchant_id}/ledgerUnified payments + refunds
GET/api/merchants/{merchant_id}/connectOpay Connect account status
POST/api/merchants/{merchant_id}/connectStart Connect onboarding
POST/api/merchants/{merchant_id}/payment-linksCreate Payment Link (active merchant)

Live vs test keys

  • opay_sk_live_* — production ledger and settlement
  • opay_sk_test_* — integration testing (read-only GET; writes return 403)

Request signing (HMAC)

Server SDKs and the WooCommerce plugin sign every request with X-Opay-Timestamp (Unix seconds) and X-Opay-Signature. Requests older than 5 minutes are rejected.

HMAC-SHA256(secret, timestamp + rawBody) → hex

Outbound webhooks

Register HTTPS endpoints via Merchant Center session. Opay POSTs signed JSON events to your server.

payment.succeeded · payment.failed · refund.created · payout.paid · payout.failed · connect.updated · balance.updated

Node.js SDK

Official client with automatic HMAC signing — see repo path: packages/opay-node

Code examples

curl -X GET "https://www.opay.com.hk/api/merchants/YOUR_MERCHANT_UUID/overview" \
  -H "X-Opay-Api-Key: opay_sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

OpenAPI specification

Machine-readable API reference (OpenAPI 3.0). Import into Swagger, Redoc, or Postman.

Interactive API reference →Download openapi.yaml