Overview
Merchant API overview
One transport, one signature scheme, five endpoints. There is no SDK to install, no OAuth flow and no token to refresh — a merchant ID, a secret key and an MD5 hash over ordered values is the entire authentication model.
Last updated 2026-10-24
Transport and format
All business endpoints are HTTP POST with application/x-www-form-urlencoded bodies, encoded as UTF-8. Responses are JSON with a numeric code (1 success, 0 failure), a message, a server timestamp and a data object.
The base URL is issued with your merchant account over Telegram. Every request carries user_id and a sign field; there is no session, so a request is authorised purely by the signature.
| Property | Value |
|---|---|
| Method | HTTP POST |
| Content type | application/x-www-form-urlencoded |
| Charset | UTF-8 |
| Signature | MD5, 32 lowercase hex |
| Callback body | JSON POST, reply plain text SUCCESS |
Endpoints
Five endpoints cover collection, disbursement and reconciliation.
| Endpoint | Purpose |
|---|---|
| POST /api/submit/submitCollect | Create a collection order (pay_type 1 = Scan & Pay, 2 = native) |
| POST /api/submit/submitPayout | Create a payout to an Indian bank account |
| POST /api/payuser/getBalance | Balance, frozen balance and dispute hold |
| POST /api/orderquery/collectStatus | Collection order state and callback delivery state |
| POST /api/orderquery/payoutStatus | Payout order state |
Quick start
A collection request with a valid signature, start to finish.
# 1. gather the values USER_ID=10093 ORDER=MCH20261024001 AMOUNT=1000 PAY_TYPE=1 CALLBACK=https://merchant.com/callback KEY=your_secret_key # 2. sign: md5(user_id + merchant_order_no + amount + pay_type + callback_url + key) SIGN=$(printf "%s" "$USER_ID$ORDER$AMOUNT$PAY_TYPE$CALLBACK$KEY" | md5sum | cut -d' ' -f1) # 3. submit curl -X POST "$BASE_URL/submit/submitCollect" \ -d "user_id=$USER_ID" \ -d "merchant_order_no=$ORDER" \ -d "pay_type=$PAY_TYPE" \ -d "amount=$AMOUNT" \ -d "callback_url=$CALLBACK" \ -d "sign=$SIGN"
Response envelope
code is the only field you must branch on. data is null whenever code is 0.
{
"code": 1,
"msg": "提交成功",
"time": 1719000000,
"data": {
"platform_order_no": "P202610240830150001234",
"merchant_order_no": "MCH20261024001",
"amount": 1000,
"fee": 30.00,
"pay_type": 1,
"status": 1,
"pay_link": "https://pay.example.com/pay/xxxxx"
}
}FAQ
Do I need to whitelist my server IP?
No. Requests are authorised by signature only. Ask us on Telegram if you want IP allow-listing as an extra layer.
Is there a sandbox?
Yes — a test merchant ID and key are issued on request. The endpoints and signature rules are identical to production.