01 接口总览

所有接口均需按第 2 节的签名规范鉴权。查询接口是订单最终状态的权威来源；异步通知可能重复、延迟或耗尽重试，收到通知后仍建议查单核对。

02 签名与鉴权

2.1 请求头

每个请求必须携带以下 5 个 Header：

2.2 签名算法

算法：HMAC-SHA256，密钥为 api_secret，结果取小写 hex。待签名串固定为 8 段，以换行符 \n 连接。某段为空时该段留空，但分隔符不可省略：

规范化规则：

1. METHOD 大写（如 POST、GET）。
2. PATH 为实际请求路径，含路径参数的真实值（如 /api/v1/payin/PO20260829000123），不是路由模板。
3. QUERY 为规范化后的查询串：参数按键升序、同键多值按值升序，键和值分别做百分号编码后以 k=v 用 & 连接；无查询参数时为空串。
4. 最后一段是原始请求体字节的 SHA-256 小写 hex；GET 等无 body 请求对空字节串取哈希，即 e3b0c442…7852b855。不要先反序列化再重新序列化 body，必须对实际发送的字节计算。

2.3 Python 签名示例

import hashlib, hmac, time, uuid, requests
from urllib.parse import urlencode

APP_ID = "your_app_id"
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE = "https://<platform-host>"

def canonical_query(params: dict) -> str:
    if not params:
        return ""
    pairs = []
    for k in sorted(params):
        vs = params[k] if isinstance(params[k], list) else [params[k]]
        for v in sorted(map(str, vs)):
            pairs.append((str(k), v))
    # 必须使用 urlencode：它与平台的 URL QueryEscape 一致，空格编码为 +。
    return urlencode(pairs)

def sign(method: str, path: str, query: dict, body: bytes, ts: str, nonce: str) -> str:
    body_sha = hashlib.sha256(body).hexdigest()
    source = "\n".join([
        method.upper(), path, canonical_query(query),
        APP_ID, API_KEY, ts, nonce, body_sha,
    ])
    return hmac.new(API_SECRET.encode(), source.encode(), hashlib.sha256).hexdigest()

def request(method: str, path: str, query: dict | None = None, body: bytes = b""):
    ts = str(int(time.time()))
    nonce = uuid.uuid4().hex
    headers = {
        "X-App-Id": APP_ID,
        "X-Api-Key": API_KEY,
        "X-Timestamp": ts,
        "X-Nonce": nonce,
        "X-Sign": sign(method, path, query or {}, body, ts, nonce),
        "Content-Type": "application/json",
    }
    url = BASE + path + (("?" + urlencode(query)) if query else "")
    return requests.request(method, url, headers=headers, data=body, timeout=10)

2.4 注意事项

• 商户身份由平台从已验签的凭证解析，请求体中不接受、也无法传入商户号。
• 防重放存储不可用时平台会直接拒绝请求（返回服务不可用类错误码），请退避重试，勿降级绕过签名。

03 统一响应与错误码

所有接口返回统一信封：

{
  "code": 0,
  "message": "成功",
  "data": { },
  "trace_id": "…",
  "timestamp": 1756450000
}

• code = 0 表示成功；失败时 data 省略。
• 请按 code 分支处理，不要解析 message 文案，文案会本地化、会调整。
• 联系平台排障时请提供 trace_id。

04 金额、币种与幂等

• 金额一律为主单位十进制字符串，如 "100.00"；小数位必须与币种精度一致（各币种精度由平台提供），多余小数或非法格式会被拒绝，平台不做四舍五入。
• channel_code 由商户显式指定，一个通道唯一对应一个方向和一个币种。
• 创建幂等键为 merchant_request_id（商户维度唯一）：
  • 完全相同的请求重发 → 返回首次创建的订单，不会产生第二笔；
  • 同一 merchant_request_id 修改了金额、通道、收款人等任一关键要素 → 返回 10003 冲突，不会创建新订单，此时应改用查单接口获取原订单结果；
  • 因此不要复用 merchant_request_id 来换金额／换通道／换收款人；重新下单请换新的 merchant_request_id。

05 代收 Payin

5.1 创建订单 POST /api/v1/payin/create

响应 data：

{
  "url": "https://…收银台地址…",
  "payin_order_no": "PO…",
  "merchant_order_no": "…",
  "amount": "100.00",
  "currency": "PKR",
  "channel_code": "…",
  "pay_method": "…",
  "status": 2,
  "channel_order_no": "上游订单号，可能为 null",
  "provider_pay_url": "上游支付链接，可能为 null",
  "provider_qr_code": "上游二维码内容，可能为 null",
  "fail_code": "",
  "fail_reason": null
}

下单失败不影响信封语义：订单已受理即返回 code=0，失败通过 status 与 fail_code 表达。

5.2 查询订单 GET /api/v1/payin/{payin_order_no}

响应 data 字段：payin_order_no、merchant_no、merchant_order_no、merchant_request_id、status、amount、currency、channel_code、pay_method、channel_order_no、provider_pay_url、provider_qr_code（仅可继续支付状态返回）、notify_url、return_url、expire_time、success_time、fail_code、fail_reason、created_at。时间字段为 RFC3339 格式。

5.3 收款订单状态

06 代付 Payout

6.1 创建订单 POST /api/v1/payout/create

响应 data：

{ "payout_order_no": "PT…", "status": 1 }

6.2 查询订单 GET /api/v1/payout/{payout_order_no}

响应 data 字段：payout_order_no、merchant_order_no、amount、currency、status、status_text、fail_code、fail_reason、receiver_account（脱敏）、success_time、created_at。

6.3 出款订单状态

07 通道列表 GET /api/v1/channel/list

返回本商户已开通的通道。下单用的 channel_code 从这里取；平台关闭某条通道后它会从列表中消失，用已消失的通道下单返回 10006。

查询参数：biz_type（1=代收，2=代付，缺省 1）、page（默认 1）、size（默认 20，最大 100；超过 100 按 100 处理，不报错）。

响应 data：page、size、total、list。list 每项包含：

单笔金额上下限不在本接口返回：它是上游的技术约束、会随上游调整而变，以下单接口的实时判定为准。建议在本地缓存一段时间后刷新，不要每笔订单调用一次。

08 余额查询 GET /api/v1/balance

无请求参数，身份来自签名凭证。响应 data：

{
  "as_of": "2026-08-29T12:00:00Z",
  "balances": [
    {
      "currency": "PKR",
      "available_balance": "12345.00",
      "frozen_balance": "100.00",
      "total_balance": "12445.00"
    }
  ]
}

金额均为主单位字符串。总余额 = 可用 + 冻结。

09 异步通知

订单进入可通知终态（SUCCESS／FAIL）后，平台向商户推送通知：

• 代收：优先使用下单时的 notify_url，为空则用商户默认收款通知地址；
• 代付：使用商户默认出款通知地址；
• 地址未配置则跳过通知，请依赖查单。

9.1 通知报文

POST，JSON body：

{
  "biz_type": "PAYIN",
  "order_no": "PO…",
  "merchant_order_no": "…",
  "merchant_no": "…",
  "amount": "100.00",
  "currency": "PKR",
  "status": "SUCCESS",
  "fail_code": "",
  "fail_reason": "",
  "finished_at": "2026-08-29T12:00:00Z",
  "notified_at": "2026-08-29T12:00:05Z"
}

• biz_type：PAYIN 或 PAYOUT；status：SUCCESS 或 FAIL。
• 通知携带与商户请求完全相同规范的 5 个签名 Header（第 2 节），对通知目标 URL 的实际路径和查询参数签名。商户可复用自己的签名代码验签，必须验签后再处理。

9.2 应答约定

商户收到并处理后必须返回：HTTP 200，响应体为纯文本 success（去除首尾空白后严格等于）。其他任何响应视为投递失败。平台请求超时 5 秒，不跟随重定向，响应体最多读取 1 KiB。

9.3 重试与幂等

• 至少一次（at-least-once）语义，通知可能重复。请以 biz_type + order_no 幂等处理，重复通知直接返回 success。
• 投递失败最多重试 3 次（总计 4 次），间隔约 15 秒 / 1 分钟 / 5 分钟；超过 30 分钟未成功则停止。
• 通知耗尽后订单状态不变；最终状态以查单接口为准，建议对长时间未收到通知的订单主动轮询。

9.4 商户侧验签示例（Python / Flask）

@app.post("/notify")
def on_notify():
    body = request.get_data()          # 原始字节，勿先解析再序列化
    ts = request.headers.get("X-Timestamp", "")
    nonce = request.headers.get("X-Nonce", "")
    got = request.headers.get("X-Sign", "")
    want = sign("POST", request.path, dict(request.args), body, ts, nonce)
    if not hmac.compare_digest(got, want):
        return "invalid sign", 401
    if abs(time.time() - int(ts)) > 300:
        return "expired", 401
    data = json.loads(body)
    handle_idempotently(data["biz_type"], data["order_no"], data["status"])
    return "success", 200

10 对接最佳实践

1. 以查单为准：通知用于加速，查单接口是最终事实。
2. 幂等三原则：新订单换新 merchant_request_id；收到 10003 冲突去查单而不是重试；通知按订单号幂等消费。
3. 按码编程：状态用数值枚举、失败原因用 fail_code 判断；message、status_text、fail_reason 仅用于展示。
4. PENDING_VERIFY 不是失败：收付款订单进入 7 时保持等待，切勿重复下单，代付侧重复下单可能造成双重打款。
5. 可用性类错误退避重试（10000／10004／20006），参数类错误（10001／10005／10006）修正后再发。
6. 保护好 api_secret：仅存服务端；怀疑泄露立即联系平台轮换。

11 联调闭环与验收

完成以下 5 项即可进入验收：

1. 使用平台提供的测试凭据完成一次代收和一次代付。
2. 对创建请求做同幂等键重发，确认不会产生第二笔订单。
3. 接收并验签通知；故意让首次应答失败，确认重复通知可被幂等消费。
4. 对每笔订单以查单接口确认最终状态和金额。
5. 验收通过后，由平台单独开通生产凭据、IP 白名单、通道和币种；测试凭据不得复用。

01 Endpoints

Every endpoint is authenticated by the signature scheme in section 2. The query endpoints are the authoritative source of an order's final state. Asynchronous notifications may repeat, arrive late, or exhaust their retries, so reconcile with a query even after a notification arrives.

02 Signing and authentication

2.1 Request headers

Every request must carry these five headers:

2.2 Signature algorithm

HMAC-SHA256 keyed with api_secret, output as lowercase hex. The string to sign is always eight segments joined by newline \n. An empty segment stays empty, but the separator is never omitted:

Canonicalization rules:

1. METHOD is uppercase, for example POST or GET.
2. PATH is the actual request path with real path parameter values, for example /api/v1/payin/PO20260829000123, not the route template.
3. QUERY is the canonicalized query string: parameters sorted by key ascending, repeated keys sorted by value ascending, keys and values percent-encoded separately, joined as k=v with &. Empty when there are no query parameters.
4. The last segment is the lowercase SHA-256 hex of the raw request body bytes. Requests without a body, such as GET, hash the empty byte string, giving e3b0c442…7852b855. Never deserialize and re-serialize the body first; hash exactly the bytes you send.

2.3 Python signing example

import hashlib, hmac, time, uuid, requests
from urllib.parse import urlencode

APP_ID = "your_app_id"
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
BASE = "https://<platform-host>"

def canonical_query(params: dict) -> str:
    if not params:
        return ""
    pairs = []
    for k in sorted(params):
        vs = params[k] if isinstance(params[k], list) else [params[k]]
        for v in sorted(map(str, vs)):
            pairs.append((str(k), v))
    # Use urlencode: it matches the platform's URL QueryEscape, encoding spaces as +.
    return urlencode(pairs)

def sign(method: str, path: str, query: dict, body: bytes, ts: str, nonce: str) -> str:
    body_sha = hashlib.sha256(body).hexdigest()
    source = "\n".join([
        method.upper(), path, canonical_query(query),
        APP_ID, API_KEY, ts, nonce, body_sha,
    ])
    return hmac.new(API_SECRET.encode(), source.encode(), hashlib.sha256).hexdigest()

def request(method: str, path: str, query: dict | None = None, body: bytes = b""):
    ts = str(int(time.time()))
    nonce = uuid.uuid4().hex
    headers = {
        "X-App-Id": APP_ID,
        "X-Api-Key": API_KEY,
        "X-Timestamp": ts,
        "X-Nonce": nonce,
        "X-Sign": sign(method, path, query or {}, body, ts, nonce),
        "Content-Type": "application/json",
    }
    url = BASE + path + (("?" + urlencode(query)) if query else "")
    return requests.request(method, url, headers=headers, data=body, timeout=10)

2.4 Notes

• Your merchant identity is resolved by the platform from the verified credentials. A merchant number in the request body is neither accepted nor possible.
• When the replay-protection store is unavailable the platform rejects the request outright with an availability error code. Back off and retry; never downgrade to bypass signing.

03 Response envelope and error codes

Every endpoint returns the same envelope:

{
  "code": 0,
  "message": "成功",
  "data": { },
  "trace_id": "…",
  "timestamp": 1756450000
}

• code = 0 means success; data is omitted on failure.
• Branch on code, never parse message: the text is localized and subject to change.
• Quote trace_id when contacting the platform about a request.

04 Amounts, currencies and idempotency

• Amounts are always major-unit decimal strings such as "100.00". The number of decimals must match the currency's precision, which the platform provides. Extra decimals or malformed values are rejected, and the platform never rounds.
• channel_code is chosen explicitly by you. One channel maps to exactly one direction and one currency.
• The creation idempotency key is merchant_request_id, unique per merchant:
  • Resending an identical request returns the order created the first time; no second order is produced.
  • Reusing the same merchant_request_id with a changed amount, channel, recipient or any other key element returns 10003 and does not create a new order. Use the query endpoint to retrieve the original order instead.
  • So never reuse a merchant_request_id to change an amount, channel or recipient. Place a new order with a new key.

05 Payin

5.1 Create POST /api/v1/payin/create

Response data:

{
  "url": "https://…cashier page…",
  "payin_order_no": "PO…",
  "merchant_order_no": "…",
  "amount": "100.00",
  "currency": "PKR",
  "channel_code": "…",
  "pay_method": "…",
  "status": 2,
  "channel_order_no": "upstream order number, may be null",
  "provider_pay_url": "upstream payment link, may be null",
  "provider_qr_code": "upstream QR payload, may be null",
  "fail_code": "",
  "fail_reason": null
}

A failed order does not change the envelope: once the order is accepted the envelope is code=0, and failure is expressed through status and fail_code.

5.2 Query GET /api/v1/payin/{payin_order_no}

Response data fields: payin_order_no, merchant_no, merchant_order_no, merchant_request_id, status, amount, currency, channel_code, pay_method, channel_order_no, provider_pay_url, provider_qr_code (returned only while the order is still payable), notify_url, return_url, expire_time, success_time, fail_code, fail_reason, created_at. Timestamps are RFC3339.

5.3 Payin order states

06 Payout

6.1 Create POST /api/v1/payout/create

Response data:

{ "payout_order_no": "PT…", "status": 1 }

6.2 Query GET /api/v1/payout/{payout_order_no}

Response data fields: payout_order_no, merchant_order_no, amount, currency, status, status_text, fail_code, fail_reason, receiver_account (masked), success_time, created_at.

6.3 Payout order states

07 Channel list GET /api/v1/channel/list

Returns the channels opened to you. Take the channel_code you order with from here. When the platform closes a channel for you it disappears from this list, and ordering on it returns 10006.

Query parameters: biz_type (1 = payin, 2 = payout, default 1), page (default 1), size (default 20, maximum 100; a larger value is clamped to 100 rather than rejected).

Response data: page, size, total, list. Each item of list contains:

Per-order amount limits are not returned here: they are an upstream technical constraint that changes as the upstream adjusts, so the create endpoint's live check governs. Cache this list for a while and refresh periodically rather than calling it per order.

08 Balance GET /api/v1/balance

No request parameters; your identity comes from the signed credentials. Response data:

{
  "as_of": "2026-08-29T12:00:00Z",
  "balances": [
    {
      "currency": "PKR",
      "available_balance": "12345.00",
      "frozen_balance": "100.00",
      "total_balance": "12445.00"
    }
  ]
}

All amounts are major-unit strings. Total = available + frozen.

09 Asynchronous notifications

Once an order reaches a notifiable terminal state (SUCCESS or FAIL) the platform pushes a notification:

• Payin: the notify_url given at creation, falling back to your default payin notification URL.
• Payout: your default payout notification URL.
• If no URL is configured the notification is skipped; rely on the query endpoint.

9.1 Notification payload

POST with a JSON body:

{
  "biz_type": "PAYIN",
  "order_no": "PO…",
  "merchant_order_no": "…",
  "merchant_no": "…",
  "amount": "100.00",
  "currency": "PKR",
  "status": "SUCCESS",
  "fail_code": "",
  "fail_reason": "",
  "finished_at": "2026-08-29T12:00:00Z",
  "notified_at": "2026-08-29T12:00:05Z"
}

• biz_type is PAYIN or PAYOUT; status is SUCCESS or FAIL.
• Notifications carry the same five signature headers under exactly the same rules as merchant requests (section 2), signed over the notification URL's actual path and query. Reuse your own signing code to verify, and always verify before acting.

9.2 Acknowledgement

After receiving and processing a notification you must return HTTP 200 with the plain-text body success, matched exactly after trimming whitespace. Anything else counts as a failed delivery. The platform times out after 5 seconds, does not follow redirects, and reads at most 1 KiB of the response.

9.3 Retries and idempotency

• Delivery is at-least-once, so notifications may repeat. Deduplicate on biz_type + order_no and return success for repeats.
• A failed delivery is retried up to 3 times (4 attempts in total) at roughly 15 seconds, 1 minute and 5 minutes, and stops after 30 minutes.
• Exhausted notifications do not change the order state. The query endpoint is authoritative; poll orders whose notification has not arrived for a long time.

9.4 Verification example (Python / Flask)

@app.post("/notify")
def on_notify():
    body = request.get_data()          # raw bytes; never parse then re-serialize
    ts = request.headers.get("X-Timestamp", "")
    nonce = request.headers.get("X-Nonce", "")
    got = request.headers.get("X-Sign", "")
    want = sign("POST", request.path, dict(request.args), body, ts, nonce)
    if not hmac.compare_digest(got, want):
        return "invalid sign", 401
    if abs(time.time() - int(ts)) > 300:
        return "expired", 401
    data = json.loads(body)
    handle_idempotently(data["biz_type"], data["order_no"], data["status"])
    return "success", 200

10 Integration practices

1. Trust the query, not the notification. Notifications only make you faster; the query endpoint is the final truth.
2. Three idempotency rules. New order, new merchant_request_id. On 10003, query instead of retrying. Consume notifications idempotently by order number.
3. Program against codes. Use the numeric state enums and fail_code; message, status_text and fail_reason are for display only.
4. PENDING_VERIFY is not a failure. Keep waiting when an order reaches 7 and never re-submit; on the payout side a re-submission can pay twice.
5. Back off on availability errors (10000, 10004, 20006). Fix parameter errors (10001, 10005, 10006) before resending.
6. Protect api_secret. Keep it server-side only, and contact the platform to rotate it the moment you suspect exposure.

11 Integration test and acceptance

Complete these five steps to enter acceptance:

1. Use the platform's test credentials to complete one payin and one payout.
2. Resend a create request with the same idempotency key and confirm no second order appears.
3. Receive and verify a notification; deliberately fail the first acknowledgement and confirm the repeat is consumed idempotently.
4. Confirm each order's final state and amount through the query endpoint.
5. After acceptance the platform issues production credentials, IP allowlist, channels and currencies separately. Test credentials are never reused.