01 接入说明

开通时平台提供：环境地址、app_id、api_key、api_secret，以及本商户已开通的支付方式清单（含各方式支持的币种与收付方向）。商户需提供：收款与出款的通知地址、服务器出口 IP（加入白名单后才能调用接口）。

1.1 通用约定

• 请求与响应均为 JSON，UTF-8 编码；所有接口按第 2 节签名。
• 统一响应：{"code": 0, "message": "成功", "data": {…}, "trace_id": "…", "timestamp": 1756450000}。code=0 表示请求已受理，不表示支付成功，订单结果看 data.status；失败时无 data。排障时提供 trace_id。
• data 中的字段一律为字符串，无值为空串 ""，不会出现 null。
• 金额为主单位十进制字符串，如 "100.00"；小数位不得超过币种精度，不补零也可，平台不做四舍五入。
• 时间为 RFC3339 格式的 UTC 时间，如 2026-09-11T08:00:00Z。
• 订单状态 status 为字符串枚举，取值见第 9.1 节；通知中的 status 只有 SUCCESS 与 FAIL。
• merchant_order_no 是商户订单号，也是幂等键：同一订单号重发相同内容返回原订单；内容不同返回 10003，不会产生第二笔。收不到响应时用原订单号原样重发，不要换号。

02 签名

2.1 请求头

2.2 签名算法

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

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

2.3 签名示例（Python）

其他语言按同样规则实现即可。使用前替换示例域名和三项凭据；api_secret 只保存在服务端。

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://api.example.com"

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))
    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",
    }
    query_string = canonical_query(query or {})
    url = BASE + path + (("?" + query_string) if query_string else "")
    return requests.request(method, url, headers=headers, data=body, timeout=10, allow_redirects=False)

2.4 签名测试向量

接入时先用下面三组向量自检，逐段比对签名原文，再比最终签名。三组凭据固定为 app_id=app_demo、api_key=key_demo、api_secret=secret_demo、X-Timestamp=1789000000、X-Nonce=nonce_demo。签名原文中的换行是真实换行符。

2.5 排查

• 20001：A 组不过是段序或分隔符错；B 组不过是 body 哈希没按实际字节算；C 组不过是查询串规范化不一致，JavaScript 的 encodeURIComponent 默认不转义 ! ' ( ) *。三组都过仍失败，检查 api_secret 是否用错环境、PATH 是否写成了路由模板。
• 偶发 20001 或时间戳报错：服务器时间漂移超过 300 秒，做 NTP 同步；X-Nonce 重复也会被拒。
• 20003：出口 IP 不在白名单内，这一层在验签之前。经 NAT 或多可用区部署时出口 IP 可能不止一个，全部提供给技术支持。

03 代收下单 POST /api/v1/payin/create

3.1 请求参数

3.2 响应参数

{
  "code": 0,
  "message": "成功",
  "data": {
    "payin_order_no": "PO202609110001",
    "merchant_order_no": "M202609110001",
    "amount": "100.00",
    "currency": "PKR",
    "pay_method": "JAZZCASH",
    "pay_method": "JAZZCASH",
    "status": "PENDING",
    "cashier_url": "https://cashier.example.com/orderPage/PO202609110001?t=…",
    "pay_url": "https://pay.example.com/PO202609110001",
    "qr_code": "",
    "channel_order_no": "",
    "fail_code": "",
    "fail_reason": ""
  },
  "trace_id": "…",
  "timestamp": 1789000000
}

04 代收查单 GET /api/v1/payin/{payin_order_no}

路径参数为平台订单号。查单结果是订单状态的权威来源；通知可能重复、延迟或耗尽重试，收到通知后仍以查单为准。

{
  "payin_order_no": "PO202609110001",
  "merchant_order_no": "M202609110001",
  "status": "SUCCESS",
  "amount": "100.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "pay_method": "JAZZCASH",
  "channel_order_no": "JC8823717",
  "pay_url": "",
  "qr_code": "",
  "notify_url": "https://merchant.example.com/notify",
  "return_url": "",
  "expire_time": "2026-09-11T08:30:00Z",
  "success_time": "2026-09-11T08:05:12Z",
  "fail_code": "",
  "fail_reason": "",
  "created_at": "2026-09-11T08:00:00Z"
}

05 代付下单 POST /api/v1/payout/create

5.1 请求参数

缺少所选支付方式要求的收款人字段时返回 10001，message 会指出缺哪一项。

5.2 响应参数

字段与代收下单同构：payout_order_no、merchant_order_no、amount、currency、pay_method、status、fail_code、fail_reason。受理成功时 status 为 INIT，出款结果通过通知和查单获取。

{
  "payout_order_no": "PT202609110001",
  "merchant_order_no": "W202609110001",
  "amount": "500.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "status": "INIT",
  "fail_code": "",
  "fail_reason": ""
}

06 代付查单 GET /api/v1/payout/{payout_order_no}

{
  "payout_order_no": "PT202609110001",
  "merchant_order_no": "W202609110001",
  "status": "SUCCESS",
  "amount": "500.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "receiver_name": "Ali Khan",
  "receiver_account": "0300****1234",
  "receiver_bank_code": "",
  "success_time": "2026-09-11T09:12:40Z",
  "fail_code": "",
  "fail_reason": "",
  "created_at": "2026-09-11T09:10:00Z"
}

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

无请求参数，返回当前商户各币种余额。总余额 = 可用余额 + 冻结余额。

{
  "as_of": "2026-09-11T08:00:00Z",
  "balances": [
    {
      "currency": "PKR",
      "available_balance": "12345.00",
      "frozen_balance": "100.00",
      "total_balance": "12445.00"
    }
  ]
}

08 异步通知

订单进入 SUCCESS 或 FAIL 时，平台向商户通知地址发送 POST 请求。代收优先使用下单时的 notify_url，为空则用商户默认代收通知地址；代付使用商户默认代付通知地址。地址未配置则不通知，请依赖查单。

8.1 通知报文

{
  "biz_type": "PAYIN",
  "order_no": "PO202609110001",
  "merchant_order_no": "M202609110001",
  "amount": "100.00",
  "currency": "PKR",
  "status": "SUCCESS",
  "fail_code": "",
  "fail_reason": "",
  "finished_at": "2026-09-11T08:05:12Z"
}

8.2 验签

通知携带与商户请求相同的 5 个签名 Header，按第 2 节规则对通知地址的实际路径、查询参数和原始请求体签名。必须验签通过后再处理，可复用自己的签名代码：

import hmac, json, time
from flask import Flask, request
app = Flask(__name__)

@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", "")
    query = request.args.to_dict(flat=False)  # 保留同名参数的全部值
    want = sign("POST", request.path, query, body, ts, nonce)
    if not hmac.compare_digest(got, want):
        return "invalid sign", 401
    if abs(time.time() - int(ts or 0)) > 300:
        return "expired", 401
    handle_notification(json.loads(body))     # 商户实现：核对订单、金额、币种后更新本地订单
    return "success", 200

8.3 应答与重试

• 验签并处理完成（或可靠保存待处理）后，5 秒内返回 HTTP 200，响应体为纯文本 success。其他响应或超时视为失败；通知地址不得返回重定向。
• 失败后最多重试 3 次，间隔约 15 秒、1 分钟、5 分钟；超过 30 分钟停止。
• 通知可能重复或乱序。按 biz_type + order_no 定位订单，同一结果重复到达不得重复处理；收到与本地不同的结果时先查单核对再更新。
• 未收到通知不表示订单失败，以查单为准；长时间无通知时主动查单，逐步拉长间隔。

09 状态与错误码

9.1 订单状态 status

9.2 失败码 fail_code

订单为 FAIL 时有值。fail_reason 仅供展示，逻辑判断以 fail_code 为准；取值只增不改，遇到未列出的值按 UNSPECIFIED 处理。

9.3 响应码 code

code 描述本次接口调用的结果，与订单结果无关。请按 code 分支，不要解析 message 文案。

10 附录：支付方式与支持银行

代收当前支持巴基斯坦（PKR）的 JazzCash、Easypaisa 与二维码扫码；代付支持钱包与银行转账。本商户实际可用的支付方式、币种、下单编码与支持银行清单以开通时提供的为准，不要自行推测银行代码。

• pay_method 只需传支付方式本身：收付方向由接口决定（/payin/create 与 /payout/create），币种由 currency 指定，平台据此唯一确定一条支付通道。银行名称或银行代码不能替代它。建单与查单响应里回显同一个 pay_method。
• 银行代付：receiver_bank_code 按支持银行清单原样填写，receiver_account 填银行账号或 IBAN。
• 钱包代付：receiver_account 填钱包手机号，通常还需 receiver_id_no。
• 上线前用测试凭据各完成一次代收和代付，并验证：用原订单号重发不产生第二笔；篡改通知报文后验签失败；重复通知不重复处理。验收通过后由平台单独开通生产凭据，测试凭据不得复用。

01 Getting started

At onboarding the platform issues the API host, app_id, api_key, api_secret, and the list of payment methods enabled for you (with the currencies and directions each supports). You provide your payin and payout notification URLs and your server egress IPs; requests are accepted only from allowlisted IPs.

1.1 Conventions

• Requests and responses are UTF-8 JSON; every endpoint is signed as described in section 2.
• Envelope: {"code": 0, "message": "…", "data": {…}, "trace_id": "…", "timestamp": 1756450000}. code=0 means the request was accepted, not that the payment succeeded; read data.status for the order outcome. On failure data is absent. Quote trace_id when contacting support.
• Every field in data is a string. Absent values are ""; null never appears.
• Amounts are decimal strings in major units, e.g. "100.00"; at most the currency's number of decimals, trailing zeros optional, no rounding.
• Times are RFC3339 in UTC, e.g. 2026-09-11T08:00:00Z.
• status is a string enum, see section 9.1; notifications carry only SUCCESS or FAIL.
• merchant_order_no is your order number and the idempotency key: resending the same order number with the same body returns the original order; a different body returns 10003 and never creates a second order. If you get no response, resend the same order number unchanged; do not mint a new one.

02 Signing

2.1 Request headers

2.2 Algorithm

HMAC-SHA256 keyed with api_secret, lowercase hex. The signing string has exactly 8 segments joined by \n; an empty segment stays empty but its separator is never dropped:

1. METHOD in upper case.
2. PATH is the actual request path with real path parameters (e.g. /api/v1/payin/PO20260829000123), not the route template.
3. QUERY is the canonical query string: keys sorted ascending, multiple values per key sorted ascending, keys and values URL-encoded with space as + and ! ' ( ) * escaped, joined as k=v with &; empty when there are no parameters. Send the same canonical string in the request URL.
4. The last segment is the SHA-256 (lowercase hex) of the raw request body bytes; requests without a body hash the empty byte string, i.e. e3b0c442…7852b855. Hash the bytes you actually send; never re-serialise.

2.3 Signing example (Python)

Other languages follow the same rules. Replace the host and the three credentials; keep api_secret server-side only.

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://api.example.com"

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))
    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",
    }
    query_string = canonical_query(query or {})
    url = BASE + path + (("?" + query_string) if query_string else "")
    return requests.request(method, url, headers=headers, data=body, timeout=10, allow_redirects=False)

2.4 Signature test vectors

Check your implementation against these three vectors before calling the API: compare the signing string segment by segment, then the final signature. All three use app_id=app_demo, api_key=key_demo, api_secret=secret_demo, X-Timestamp=1789000000, X-Nonce=nonce_demo. Line breaks in the signing string are real newlines.

2.5 Troubleshooting

• 20001: vector A failing means wrong segment order or separators; B failing means the body hash was not computed over the exact bytes sent; C failing means query canonicalisation differs, and JavaScript's encodeURIComponent does not escape ! ' ( ) * by default. If all three pass, check that api_secret belongs to this environment and that PATH is not the route template.
• Intermittent 20001 or timestamp errors: server clock drift beyond 300 seconds; sync with NTP. A repeated X-Nonce is also rejected.
• 20003: your egress IP is not allowlisted; this check runs before signature verification. Behind NAT or across availability zones you may have several egress IPs; send all of them to support.

03 Create payin POST /api/v1/payin/create

3.1 Request

3.2 Response

{
  "code": 0,
  "message": "OK",
  "data": {
    "payin_order_no": "PO202609110001",
    "merchant_order_no": "M202609110001",
    "amount": "100.00",
    "currency": "PKR",
    "pay_method": "JAZZCASH",
    "pay_method": "JAZZCASH",
    "status": "PENDING",
    "cashier_url": "https://cashier.example.com/orderPage/PO202609110001?t=…",
    "pay_url": "https://pay.example.com/PO202609110001",
    "qr_code": "",
    "channel_order_no": "",
    "fail_code": "",
    "fail_reason": ""
  },
  "trace_id": "…",
  "timestamp": 1789000000
}

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

The path parameter is the platform order number. The query result is the authoritative order state; notifications may repeat, arrive late or exhaust their retries, so confirm with a query.

{
  "payin_order_no": "PO202609110001",
  "merchant_order_no": "M202609110001",
  "status": "SUCCESS",
  "amount": "100.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "pay_method": "JAZZCASH",
  "channel_order_no": "JC8823717",
  "pay_url": "",
  "qr_code": "",
  "notify_url": "https://merchant.example.com/notify",
  "return_url": "",
  "expire_time": "2026-09-11T08:30:00Z",
  "success_time": "2026-09-11T08:05:12Z",
  "fail_code": "",
  "fail_reason": "",
  "created_at": "2026-09-11T08:00:00Z"
}

05 Create payout POST /api/v1/payout/create

5.1 Request

If a beneficiary field required by the chosen method is missing, the response is 10001 and message names the field.

5.2 Response

Same shape as create payin: payout_order_no, merchant_order_no, amount, currency, pay_method, status, fail_code, fail_reason. On acceptance status is INIT; the outcome arrives by notification and query.

{
  "payout_order_no": "PT202609110001",
  "merchant_order_no": "W202609110001",
  "amount": "500.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "status": "INIT",
  "fail_code": "",
  "fail_reason": ""
}

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

{
  "payout_order_no": "PT202609110001",
  "merchant_order_no": "W202609110001",
  "status": "SUCCESS",
  "amount": "500.00",
  "currency": "PKR",
  "pay_method": "JAZZCASH",
  "receiver_name": "Ali Khan",
  "receiver_account": "0300****1234",
  "receiver_bank_code": "",
  "success_time": "2026-09-11T09:12:40Z",
  "fail_code": "",
  "fail_reason": "",
  "created_at": "2026-09-11T09:10:00Z"
}

07 Balances GET /api/v1/balance

No parameters. Returns your balances per currency. Total = available + frozen.

{
  "as_of": "2026-09-11T08:00:00Z",
  "balances": [
    {
      "currency": "PKR",
      "available_balance": "12345.00",
      "frozen_balance": "100.00",
      "total_balance": "12445.00"
    }
  ]
}

08 Notifications

When an order reaches SUCCESS or FAIL, the platform POSTs to your notification URL. Payin uses the order's notify_url, falling back to your default payin URL; payout uses your default payout URL. If no URL is configured nothing is sent; rely on queries.

8.1 Payload

{
  "biz_type": "PAYIN",
  "order_no": "PO202609110001",
  "merchant_order_no": "M202609110001",
  "amount": "100.00",
  "currency": "PKR",
  "status": "SUCCESS",
  "fail_code": "",
  "fail_reason": "",
  "finished_at": "2026-09-11T08:05:12Z"
}

8.2 Verification

Notifications carry the same 5 signature headers as your requests, signed per section 2 over the notification URL's actual path, query string and raw body. Verify before processing; you can reuse your own signing code:

import hmac, json, time
from flask import Flask, request
app = Flask(__name__)

@app.post("/notify")
def on_notify():
    body = request.get_data()                 # raw bytes; never parse and re-serialise
    ts = request.headers.get("X-Timestamp", "")
    nonce = request.headers.get("X-Nonce", "")
    got = request.headers.get("X-Sign", "")
    query = request.args.to_dict(flat=False)  # keep every value of repeated keys
    want = sign("POST", request.path, query, body, ts, nonce)
    if not hmac.compare_digest(got, want):
        return "invalid sign", 401
    if abs(time.time() - int(ts or 0)) > 300:
        return "expired", 401
    handle_notification(json.loads(body))     # yours: verify order, amount, currency, then update
    return "success", 200

8.3 Acknowledgement and retries

• After verifying and processing (or durably queuing) the notification, reply within 5 seconds with HTTP 200 and the plain-text body success. Anything else, or a timeout, counts as failure; the URL must not redirect.
• Failed deliveries are retried up to 3 times, after roughly 15 seconds, 1 minute and 5 minutes; retries stop after 30 minutes.
• Notifications may repeat or arrive out of order. Locate the order by biz_type + order_no; do not process the same result twice; when a result differs from what you hold, query first, then update.
• A missing notification does not mean failure. The query endpoint is authoritative; poll it with increasing intervals when no notification arrives.

09 Statuses and codes

9.1 Order status

9.2 Failure code fail_code

Set when the order is FAIL. fail_reason is display text only; branch on fail_code. The set only grows; treat unknown values as UNSPECIFIED.

9.3 Response code

code describes this API call, not the order. Branch on code; do not parse message.

10 Appendix: payment methods and banks

Payin currently supports JazzCash, Easypaisa and QR payments in Pakistan (PKR); payout supports wallet and bank transfers. The methods, currencies, channel codes and supported banks available to you are the ones issued at onboarding; do not guess bank codes.

• pay_method carries the payment method alone: direction comes from the endpoint (/payin/create vs /payout/create) and the currency from currency, which together identify exactly one payment channel. A bank name or bank code never replaces it. Create and query responses echo the same pay_method.pay_method in create and query responses echoes the method actually used; it is not a request parameter.
• Bank payouts: receiver_bank_code exactly as listed in the supported-bank list; receiver_account is the bank account number or IBAN.
• Wallet payouts: receiver_account is the wallet mobile number; receiver_id_no is usually required.
• Before go-live, complete one payin and one payout with test credentials and verify that: resending under the same order number does not create a second order; a tampered notification fails verification; a repeated notification is not processed twice. Production credentials are issued separately after acceptance; test credentials must not be reused.