Antspay API 文档 v3.7

Antspay OpenAPI · Pay-in / Disbursement / Wallet · 更新时间：2026-09-13

1) 概览

基础域名: https://api.antspay.vip（OpenAPI：代收 / 代付 / 查单 / 余额）
收银台域名: https://antspage.vip（代收响应 paymentUrl 指向此域名，付款人在钱包内打开）
文档站点: https://docs.antspay.vip
认证方式: Authorization: Basic <base64(mid:signature)>
时间戳: Request-Time（13 位毫秒时间戳，与平台时间偏差不得超过 ±60 秒，必须与签名中使用的一致）
IP 白名单: 请求必须来自白名单中的 IP；未配置白名单时，平台拒绝该商户的全部 OpenAPI 请求
货币: PKR
支付类型 (pm):
JAZZCASH, JC直连
EASYPAISA, EP直连
JAZZCASH_CS, JC收银台模式
EASYPAISA_CS, EP收银台模式

2) 签名规则

POST 请求签名

POST 接口请求体固定采用 application/json 格式。

签名字符串: signatureString = Request-Time + "." + body

防重放依赖 Request-Time ±60 秒；请勿在签名串中插入空格或换行。

用于签名的 body 必须与实际发送的原始 JSON 请求体完全一致，包括字段顺序、嵌套对象顺序、字段名大小写以及空值表现形式。签名完成后，请勿再次调整 JSON 字段顺序或重新序列化请求体。

计算方式:

signature = hex(hmac-sha256(signatureString, secret))

认证头:

Authorization: Basic base64(mid:signature)

建议先按最终发送顺序生成 JSON 字符串，再同时复用于签名计算与 HTTP 请求发送，以避免因 JSON 重排导致验签失败。

GET 请求签名

将查询参数 按 key 升序排序，拼接成: key=value，以 & 连接

签名字符串: signatureString = Request-Time + "." + queryParams

3) 代收（入金）/ Pay-in

3.1 代收订单提交

接口: POST https://api.antspay.vip/api/mcht/payment/submit

请求格式: 请求体必须为 application/json，并且参与签名的 JSON 字符串必须与实际发送的请求体内容及字段顺序完全一致。

请求头

Content-Type: application/json
Authorization: Basic <base64(mid:signature)>
Request-Time: <13 位毫秒时间戳>

Body 参数

字段	类型	必填	说明	示例
amount	number	是	数值类型，保留两位小数；不是字符串	`100.00`
pm	string	是	支付类型: `JAZZCASH`, JC直连 `EASYPAISA`, EP直连 `JAZZCASH_CS`, JC收银台模式 `EASYPAISA_CS`, EP收银台模式	`JAZZCASH`
ref	string	是	商户订单号，必须唯一	`UNIQUE_ORDER_ID_01`
payer.email	string	是	付款人邮箱	`[email protected]`
payer.name	string	是	付款人姓名	`abc`
payer.phone	string	是	付款人电话	`03012933333`
redirect	string	否	支付完成后跳转地址	`https://example.com`
callbackUrl	string	是	异步通知回调地址	`https://example.com`

请求体示例

{
  "amount": 100.00,
  "pm": "JAZZCASH",
  "ref": "UNIQUE_ORDER_ID_01",
  "payer": {
    "email": "[email protected]",
    "name": "abc",
    "phone": "03012933333"
  },
  "redirect": "https://example.com",
  "callbackUrl": "https://example.com"
}

Python 示例

import time, hmac, hashlib, base64, json, requests

mid = "c70f1719017e290354017d1c101d0cc288d06ceb"
secret = "ME2VRe6tWH6weK/NAUJA5lhmewHkB23rA6CdWlrHrAs+/E/E3j3eG3io/GCHbQKqMMurfTNrBj/R4Yy84UziM5YJheiKFKbsWQc5xRoE46E3/0EYy4ZjbK9jhwGyHS+C"

url = "https://api.antspay.vip/api/mcht/payment/submit"

body = {
    "amount": 220.00,
    "pm": "JAZZCASH",
    "ref": "ORDER_SUBMIT_013",
    "payer": {
        "email": "[email protected]",
        "name": "abc",
        "phone": "03012933333"
    },
    "redirect": "https://example.com",
    "callbackUrl": "https://example.com"
}

request_time = str(int(time.time() * 1000))
body_str = json.dumps(body, ensure_ascii=False, separators=(',', ':'))
signature_str = f"{request_time}.{body_str}"

signature_hex = hmac.new(secret.encode(), signature_str.encode(), hashlib.sha256).hexdigest()
auth_header = "Basic " + base64.b64encode(f"{mid}:{signature_hex}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": auth_header,
    "Request-Time": request_time
}

resp = requests.post(url, headers=headers, data=body_str, timeout=30)
print("Status:", resp.status_code)
print("Response:", resp.text)

响应示例

{
  "success": true,
  "code": 200,
  "data": {
    "amount": "220",
    "pm": "JAZZCASH",
    "ref": "ORDER_SUBMIT_013",
    "redirect": "https://example.com",
    "currency": "PKR",
    "txid": "202509081321A6DI4P0V",
    "fee": "2.2",
    "netAmount": "217.8",
    "createTime": 1757308907315,
    "payer": {
      "name": "abc",
      "phone": "03012933333",
      "email": "[email protected]"
    },
    "paymentUrl": "https://antspage.vip/payment/x3v83q7d",
    "callbackUrl": "https://example.com"
  }
}

3.2 代收订单查询

接口:
GET https://api.antspay.vip/api/mcht/payment/retrieve?txid=<平台订单号>
GET https://api.antspay.vip/api/mcht/payment/retrieve?ref=<商户订单号>

说明: 查询参数 txid 与 ref 至少传一个；若两者同时传入，系统仅按 txid 查询并忽略 ref。

请求头

Authorization: Basic <base64(mid:signature)>
Request-Time: <13 位毫秒时间戳>

Query 参数

字段	类型	必填	说明
txid	string	条件必填	平台订单号（与 ref 至少传一个；若同时传入，优先按 txid 查询）
ref	string	条件必填	商户订单号（与 txid 至少传一个；当 txid 存在时此参数被忽略）

响应示例

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "txid": "202409061809AE4IK4EZ",
    "amount": "100.00",
    "fee": "1.00",
    "netAmount": "99.00",
    "type": "PAYMENT",
    "ref": "234d5678d345d5d6",
    "currency": "PKR",
    "status": "PAID",
    "paidTime": 1725617395000,
    "createTime": 1725617356000,
    "completeTime": 1725617395000,
    "callbackUrl": "",
    "redirectUrl": ""
  }
}

错误示例（缺少查询参数）

{
  "success": false,
  "code": 400,
  "message": "txid or ref is required"
}

3.3 代收回调数据格式

接口: POST <callbackUrl>

请求头

Content-Type: application/json
Request-Time: 1761036368112
Signature: a99a3414027ac065dc555c9196c865d0b8b5698ec1e
Accept: */*
Content-Length: 296
Host: *.*.*.*
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.14 (Java/1.8)
Accept-Encoding: gzip,deflate

回调验签

回调验签规则与请求签名一致，直接使用收到的原始 JSON 请求体参与验签。

签名字符串: Request-Time + "." + body

signature = hex(hmac-sha256(signatureString, secret))

验签步骤：读取 Request-Time、Signature 和原始 body，按规则计算后与 Signature 比对；一致即通过。

验签示例

Request-Time = 1761036368112
body = {"amount":"100.00","callbackUrl":"https://yourcallbackurl.com/callbackBody","createTime":1757914023000,"currency":"PKR","fee":"1.50","netAmount":"98.50","ref":"REF000778T1757914022506R9cTvO","status":"FAILED","txid":"2025091513276E4I443MPL5","invoiceNo":"265163123456","type":"PAYMENT"}

signatureString = 1761036368112.{"amount":"100.00","callbackUrl":"https://yourcallbackurl.com/callbackBody","createTime":1757914023000,"currency":"PKR","fee":"1.50","netAmount":"98.50","ref":"REF000778T1757914022506R9cTvO","status":"FAILED","txid":"2025091513276E4I443MPL5","invoiceNo":"265163123456","type":"PAYMENT"}

import hmac, hashlib

request_time = request.headers["Request-Time"]
signature = request.headers["Signature"]
raw_body = request.get_data(as_text=True)

signature_str = f"{request_time}.{raw_body}"
expected_signature = hmac.new(
    secret.encode(),
    signature_str.encode(),
    hashlib.sha256,
).hexdigest()

if expected_signature != signature:
    raise ValueError("invalid callback signature")

Body 参数

字段	类型	说明
amount	string	金额
callbackUrl	string	异步通知回调地址
createTime	number	创建时间（13 位毫秒时间戳）
currency	string	币种（如：PKR）
fee	string	手续费
netAmount	string	净金额
ref	string	商户订单号
status	string	订单状态（PAYING, PAID, COMPLETE, FAILED）
txid	string	平台订单号
invoiceNo	string	渠道交易号（第三方参考号）
type	string	交易类型（PAYMENT）

回调数据示例

{
  "amount": "100.00",
  "callbackUrl": "https://yourcallbackurl.com/callbackBody",
  "createTime": 1757914023000,
  "currency": "PKR",
  "fee": "1.50",
  "netAmount": "98.50",
  "ref": "REF000778T1757914022506R9cTvO",
  "status": "FAILED",
  "txid": "2025091513276E4I443MPL5",
  "invoiceNo": "265163123456",
  "type": "PAYMENT"
}

4) 代付（出金）/ Disbursement

4.1 代付订单提交

接口: POST https://api.antspay.vip/api/mcht/disbursement/create

请求格式: 请求体必须为 application/json，并且参与签名的 JSON 字符串必须与实际发送的请求体内容及字段顺序完全一致。

请求头

Content-Type: application/json
Authorization: Basic <base64(mid:signature)>
Request-Time: <13 位毫秒时间戳>

Body 参数

字段	类型	必填	说明	示例
amount	number	是	数值类型，保留两位小数；不是字符串	`100.00`
type	string	是	支付类型：`JAZZCASH`、`EASYPAISA`	`JAZZCASH`
bankAccountName	string	是	收款人姓名	`PATANGRAO`
bankAccountNumber	string	是	固定值	`0312345678`
bankCode	string	是	固定值	`ABCD`
phone	string	是	钱包账号，03 开头的钱包手机号	`03706906192`
email	string	是	持卡人邮箱	`[email protected]`
idNumber	string	是	固定值	`4210112345671`
ref	string	是	商户订单号，必须唯一	`WITHDRAW_TEST_004`
callbackUrl	string	是	异步通知回调地址	`https://example.com`

说明: 当前代付仅支持钱包出款，不支持银行卡出款。字段 bankAccountNumber 固定传 0312345678；实际钱包账号请填写在 phone 字段中；bankCode 固定传 ABCD。

请求体示例

{
    "amount": 100.00,
    "type": "JAZZCASH",
    "bankAccountName": "PATANGRAO",
    "bankAccountNumber": "0312345678",
    "bankCode": "ABCD",
    "phone": "03706906192",
    "email": "[email protected]",
    "idNumber": "4210112345671",
    "ref": "WITHDRAW_TEST_004",
    "callbackUrl": "https://example.com"
}

Python 示例

import time, hmac, hashlib, base64, json, requests

mid = "c70f1719017e290354017d1c101d0cc288d06ceb"
secret = "ME2VRe6tWH6weK/NAUJA5lhmewHkB23rA6CdWlrHrAs+/E/E3j3eG3io/GCHbQKqMMurfTNrBj/R4Yy84UziM5YJheiKFKbsWQc5xRoE46E3/0EYy4ZjbK9jhwGyHS+C"

url = "https://api.antspay.vip/api/mcht/disbursement/create"

body = {
    "amount": 100.00,
    "type": "JAZZCASH",
    "bankAccountName": "PATANGRAO",
    "bankAccountNumber": "0312345678",
    "bankCode": "ABCD",
    "phone": "03706906192",
    "email": "[email protected]",
    "idNumber": "4210112345671",
    "ref": "WITHDRAW_TEST_004",
    "callbackUrl": "https://example.com"
}

request_time = str(int(time.time() * 1000))
body_str = json.dumps(body, ensure_ascii=False, separators=(',', ':'))
signature_str = f"{request_time}.{body_str}"

signature_hex = hmac.new(secret.encode(), signature_str.encode(), hashlib.sha256).hexdigest()
auth_header = "Basic " + base64.b64encode(f"{mid}:{signature_hex}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": auth_header,
    "Request-Time": request_time
}

resp = requests.post(url, headers=headers, data=body_str, timeout=30)
print("Status:", resp.status_code)
print("Response:", resp.text)

响应示例

{
  "success": true,
  "code": 200,
  "data": {
    "amount": "100",
    "bankAccountName": "PATANGRAO",
    "bankAccountNumber": "0312345678",
    "bankCode": "ABCD",
    "ref": "WITHDRAW_TEST_004",
    "currency": "PKR",
    "callbackUrl": "https://example.com",
    "email": "[email protected]",
    "phone": "03706906192",
    "type": "JAZZCASH",
    "idNumber": "4210112345671",
    "txid": "PO202512221310089I7GRK",
    "netAmount": "100",
    "fee": "0",
    "createTime": 1766391032341
  }
}

4.2 代付订单查询

接口:
GET https://api.antspay.vip/api/mcht/disbursement/retrieve?txid=<平台订单号>
GET https://api.antspay.vip/api/mcht/disbursement/retrieve?ref=<商户订单号>

说明: 查询参数 txid 与 ref 至少传一个；若两者同时传入，系统仅按 txid 查询并忽略 ref。

请求头

Authorization: Basic <base64(mid:signature)>
Request-Time: <13 位毫秒时间戳>

Query 参数

字段	类型	必填	说明
txid	string	条件必填	平台订单号（与 ref 至少传一个；若同时传入，优先按 txid 查询）
ref	string	条件必填	商户订单号（与 txid 至少传一个；当 txid 存在时此参数被忽略）

响应示例

{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": {
    "txid": "PO202408231658A87IKRYL",
    "amount": "100.00",
    "fee": "1.00",
    "netAmount": "99.00",
    "type": "DISBURSEMENT",
    "ref": "234d5678d345d5d6",
    "currency": "PKR",
    "status": "PAID",
    "paidTime": 1725617395000,
    "createTime": 1725617356000,
    "callbackUrl": "",
    "redirectUrl": ""
  }
}

错误示例（缺少查询参数）

{
  "success": false,
  "code": 400,
  "message": "txid or ref is required"
}

4.3 代付回调数据格式

接口: POST <callbackUrl>

请求头

Content-Type: application/json
Request-Time: 1761036368112
Signature: a99a3414027ac065dc555c9196c865d0b8b5698ec1e
Accept: */*
Content-Length: 296
Host: *.*.*.*
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.14 (Java/1.8)
Accept-Encoding: gzip,deflate

回调验签

回调验签规则与请求签名一致，直接使用收到的原始 JSON 请求体参与验签。

签名字符串: Request-Time + "." + body

signature = hex(hmac-sha256(signatureString, secret))

验签步骤：读取 Request-Time、Signature 和原始 body，按规则计算后与 Signature 比对；一致即通过。

验签示例

Request-Time = 1761036368112
body = {"amount":"521.30","callbackUrl":"https://yourcallbackurl.app/webhooks/payout","createTime":1757910583000,"currency":"PKR","fee":"0.00","netAmount":"521.30","paidTime":1757910583000,"ref":"REF460128f04955612de","status":"PAID","txid":"PO202509151229664IDW3M83","invoiceNo":"ref123456790","type":"DISBURSEMENT"}

signatureString = 1761036368112.{"amount":"521.30","callbackUrl":"https://yourcallbackurl.app/webhooks/payout","createTime":1757910583000,"currency":"PKR","fee":"0.00","netAmount":"521.30","paidTime":1757910583000,"ref":"REF460128f04955612de","status":"PAID","txid":"PO202509151229664IDW3M83","invoiceNo":"ref123456790","type":"DISBURSEMENT"}

import hmac, hashlib

request_time = request.headers["Request-Time"]
signature = request.headers["Signature"]
raw_body = request.get_data(as_text=True)

signature_str = f"{request_time}.{raw_body}"
expected_signature = hmac.new(
    secret.encode(),
    signature_str.encode(),
    hashlib.sha256,
).hexdigest()

if expected_signature != signature:
    raise ValueError("invalid callback signature")

Body 参数

字段	类型	说明
amount	string	金额
callbackUrl	string	异步通知回调地址
createTime	number	创建时间（13 位毫秒时间戳）
currency	string	币种（如：PKR）
fee	string	手续费
netAmount	string	净金额
paidTime	number	支付时间（13 位毫秒时间戳）
ref	string	商户订单号
status	string	订单状态（PAYING, PAID, FAILED）
txid	string	平台订单号
invoiceNo	string	渠道交易号（第三方参考号）
type	string	交易类型（DISBURSEMENT）

回调数据示例

{
  "amount": "521.30",
  "callbackUrl": "https://yourcallbackurl.app/webhooks/payout",
  "createTime": 1757910583000,
  "currency": "PKR",
  "fee": "0.00",
  "netAmount": "521.30",
  "paidTime": 1757910583000,
  "ref": "REF460128f04955612de",
  "status": "PAID",
  "txid": "PO202509151229664IDW3M83",
  "invoiceNo": "ref123456790",
  "type": "DISBURSEMENT"
}

5) 查询余额 / Wallet Balance

接口: GET https://api.antspay.vip/api/mcht/wallet?currency=PKR

请求头

Authorization: Basic <base64(mid:signature)>
Request-Time: <13 位毫秒时间戳>

Query 参数

字段	类型	必填	说明
currency	string	是	币种（如：PKR）

Python 示例

import time, hmac, hashlib, base64, requests

mid = "c70f1719017e290354017d1c101d0cc288d06ceb"
secret = "ME2VRe6tWH6weK/NAUJA5lhmewHkB23rA6CdWlrHrAs+/E/E3j3eG3io/GCHbQKqMMurfTNrBj/R4Yy84UziM5YJheiKFKbsWQc5xRoE46E3/0EYy4ZjbK9jhwGyHS+C"

url = "https://api.antspay.vip/api/mcht/wallet"
params = {"currency": "PKR"}

request_time = str(int(time.time() * 1000))
query_str = "&".join([f"{k}={v}" for k, v in sorted(params.items())])
signature_str = f"{request_time}.{query_str}"

signature_hex = hmac.new(secret.encode(), signature_str.encode(), hashlib.sha256).hexdigest()
auth_header = "Basic " + base64.b64encode(f"{mid}:{signature_hex}".encode()).decode()

headers = {
    "Authorization": auth_header,
    "Request-Time": request_time
}

resp = requests.get(url, headers=headers, params=params, timeout=30)
print("Status:", resp.status_code)
print("Response:", resp.text)

响应示例

{
  "success": true,
  "code": 200,
  "data": [
    {
      "currency": "PKR",
      "balance": "1000",
      "freeze": "0",
      "total": "1000"
    }
  ]
}

6) 订单状态说明

代收（入金）订单状态

状态	说明
PAYING	订单已创建，正在处理中，等待付款人完成支付
PAID	付款人已完成支付，资金已到达平台账户
COMPLETE	订单已完成，资金已结算至商户账户
FAILED	订单失败，可能由于付款人未支付、支付超时或异常等原因

代付（出金）订单状态

状态	说明
PAYING	订单已创建，正在处理中，等待银行处理
PAID	资金已成功转账至收款人账户
FAILED	订单失败，可能由于银行账户信息错误、余额不足或其他异常

7) 注意事项

幂等性: ref 必须唯一，可用毫秒时间戳拼接生成。
JSON 序列化: 签名用的 JSON 必须与实际请求体完全一致。
时间戳: Request-Time 使用 13 位毫秒时间戳，允许与平台时钟偏差 ±60 秒，并与签名保持一致；请同步 NTP。
IP 白名单: 仅允许已登记的出口 IP 调用 OpenAPI；白名单为空时拒绝全部请求。请向平台提交服务器公网 IP。
回调: callbackUrl 必须公网可访问，平台会在交易状态变更时异步通知。
回调签名验证: 商户需验证回调请求的签名，确保数据完整性和安全性。
安全: secret 仅在服务端保存，严禁下发至前端或客户端。
异常处理: 请对 4xx/5xx 错误做好重试与告警，记录签名串以便排查。

商户号 (mid): <商户后台签发的 mid>
商户密钥 (secret): <商户后台签发的 secret，仅服务端保存>

代收URL: https://api.antspay.vip/api/mcht/payment/submit
代收查单URL: https://api.antspay.vip/api/mcht/payment/retrieve?txid=<平台订单号> 或 https://api.antspay.vip/api/mcht/payment/retrieve?ref=<商户订单号>（至少传一个；同时传时仅按 txid 查询）
代付URL: https://api.antspay.vip/api/mcht/disbursement/create
代付查单URL: https://api.antspay.vip/api/mcht/disbursement/retrieve?txid=<平台订单号> 或 https://api.antspay.vip/api/mcht/disbursement/retrieve?ref=<商户订单号>（至少传一个；同时传时仅按 txid 查询）
查询余额: https://api.antspay.vip/api/mcht/wallet?currency=PKR