Developers — Apay Merchant API & SDK

Overview

Apay merchant integration has two paths. For web/backend flows, call the REST API directly. For in-app purchases on iOS/Android, launch the Apay wallet through the SDK — the wallet handles authentication and signing, then calls back to your server.

📌 All API responses follow a unified Result<T> envelope, and sensitive actions require a transaction password passed in the request body. Test environment uses mode TEST with the verification code 666666.

Authentication

Every request is authenticated with an apiKey and an MD5 signature. Build the signature by sorting all parameters alphabetically (ASCII order), appending key=appSecret, and hashing the whole string with MD5.

# 1. Collect params, sort by ASCII key asc params = { amount: "100", merchantId: "M123", nonce: "abc" } # 2. Concatenate key=value pairs raw = "amount=100&merchantId=M123&nonce=abc&key=YOUR_APP_SECRET" # 3. MD5 (uppercase, 32 hex) sign = md5(raw).toUpperCase() # 4. Send sign + apiKey in headers/body

🔐 Keep appSecret server-side only. Never embed it in client apps — signing must happen on your backend.

Core endpoints

A representative slice of the merchant-facing surface (paths reflect the backend API contract):

POST/pay/createCreate a payment order

GET/pay/query?orderId=Query order status

POST/merchant/settleSettle APAY → INR

GET/merchant/balanceMerchant APAY balance

POST/merchant/refundRefund a payment

POST/webhook/registerRegister callback URL

Mobile SDK

The SDK launches the Apay wallet via Universal Link (iOS) or App Link (Android). Your app passes an order payload; Apay shows the product, amount and merchant name, the user confirms with biometrics or transaction password, and Apay returns to your app with a signed result.

// Android / iOS — launch Apay payment ApaySDK.pay({ orderId: "ORD-2026-0091", amount: 100, // APAY merchant: "GameStudio Pro", callback: "yourapp://apay/result" });

Webhooks

Subscribe to payment events so your backend learns about settlements without polling. Each webhook is signed with the same MD5 scheme so you can verify authenticity.

// POST https://your-server/apay/webhook { "event": "payment.settled", "orderId": "ORD-2026-0091", "amount": "100", "txHash": "0x9f...3a2c", "sign": "A1B2C3...F0" }

Settlement

Merchants receive APAY instantly on payment. To realize fiat, call the settle endpoint to convert APAY to INR; settlement is processed by the platform and reflected in your merchant ledger. Large amounts may require additional AML verification.

⚡ Target payment success rate ≥ 99.5% and settlement confirmation < 3s on the Polygon private chain.

Accept APAY in your product.