TayPay
商户登录

接入文档

认证与签名

app_id必填
商户应用 ID。
timestamp必填
Unix 秒级时间戳，与服务端时间误差不得超过 300 秒。
nonce必填
请求唯一随机串，同一 app_id 下不能重放。
sign_type必填
固定为 HMAC-SHA256。
sign必填
应用 secret 对规范化参数串计算出的十六进制 HMAC-SHA256。
说明
  • 计算 sign 时排除 sign、空值和非标量字段。其余字段按 ASCII 键名升序排列，key 和 value 分别 rawurlencode 后以 & 连接。
  • 使用应用 secret 对该字符串计算 HMAC-SHA256，并输出十六进制小写 sign。
  • 重试必须使用新的 nonce、timestamp 和 sign。

通道与场景

查询可用通道

GET /api/payment/channels?tenant_id=TENANT_ID&scene=pc_web
tenant_id必填
目标租户 ID。
scene
推荐传入 pc_web、mobile_web 或 app，未传时保留历史兼容列表。
说明
  • 传入 scene 后，创建订单会校验 channel 是否支持相同场景。
  • 不要使用旧文档中的固定通道示例。

订单接口

创建订单

POST /api/payment/open/v1/order/create
app_id必填
商户应用 ID。
timestamp必填
Unix 秒级时间戳，与服务端时间误差不得超过 300 秒。
nonce必填
请求唯一随机串，同一 app_id 下不能重放。
sign_type必填
固定为 HMAC-SHA256。
sign必填
应用 secret 对规范化参数串计算出的十六进制 HMAC-SHA256。
merchant_order_no必填
商户订单号，同一应用内唯一。
amount必填
订单金额。
channel必填
通过通道发现接口取得的 channel。
subject
订单标题，省略时使用 merchant_order_no。
body
订单描述。
notify_url
本订单的支付结果通知地址，优先于应用默认地址。
return_url
浏览器支付完成后的返回地址。
scene
推荐传入 pc_web、mobile_web 或 app，存在时参与签名和场景校验。

请求示例

{
  "app_id": "APP_ID",
  "merchant_order_no": "ORDER-20260920-001",
  "amount": "100.00",
  "channel": "alipay_page",
  "scene": "pc_web",
  "timestamp": 1789862400,
  "nonce": "NONCE",
  "sign_type": "HMAC-SHA256",
  "sign": "SIGN"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "merchant_order_no": "ORDER-20260920-001",
    "platform_order_no": "PAY202609200001",
    "amount": "100.00",
    "fee_amount": "1.00",
    "settlement_amount": "99.00",
    "channel": "alipay_page",
    "status": 0,
    "notify_status": 0,
    "paid_time": null,
    "settle_time": null,
    "payment_status": "unpaid",
    "payment_status_code": 0,
    "lifecycle_status": "active",
    "paid_after_closed": false,
    "closed": null,
    "pay_url": "https://gateway.example/pay/…",
    "pay_params": {}
  }
}
说明
  • pay_url 是通道网关原始支付地址，不能假定为托管收银台 URL。
  • pay_params 完全由通道决定，二维码、H5、App SDK 和链上支付字段不同。
  • 如需托管收银台，可在当前前端域名构造 /checkout/{platform_order_no}。

查询订单

POST /api/payment/open/v1/order/query
app_id必填
商户应用 ID。
timestamp必填
Unix 秒级时间戳，与服务端时间误差不得超过 300 秒。
nonce必填
请求唯一随机串，同一 app_id 下不能重放。
sign_type必填
固定为 HMAC-SHA256。
sign必填
应用 secret 对规范化参数串计算出的十六进制 HMAC-SHA256。
platform_order_no
平台订单号。
merchant_order_no
未提供平台订单号时使用的商户订单号。

请求示例

{
  "app_id": "APP_ID",
  "merchant_order_no": "ORDER-20260920-001",
  "timestamp": 1789862400,
  "nonce": "NONCE",
  "sign_type": "HMAC-SHA256",
  "sign": "SIGN"
}

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "merchant_order_no": "ORDER-20260920-001",
    "platform_order_no": "PAY202609200001",
    "amount": "100.00",
    "fee_amount": "1.00",
    "settlement_amount": "99.00",
    "channel": "alipay_page",
    "status": 0,
    "notify_status": 0,
    "paid_time": null,
    "settle_time": null,
    "payment_status": "unpaid",
    "payment_status_code": 0,
    "lifecycle_status": "active",
    "paid_after_closed": false,
    "closed": null
  }
}

关闭订单

POST /api/payment/open/v1/order/close
app_id必填
商户应用 ID。
timestamp必填
Unix 秒级时间戳，与服务端时间误差不得超过 300 秒。
nonce必填
请求唯一随机串，同一 app_id 下不能重放。
sign_type必填
固定为 HMAC-SHA256。
sign必填
应用 secret 对规范化参数串计算出的十六进制 HMAC-SHA256。
platform_order_no
平台订单号。
merchant_order_no
未提供平台订单号时使用的商户订单号。
close_source
关闭来源。
close_source_id
关闭来源的关联标识。
close_reason
关闭原因。
close_message
关闭说明。

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "merchant_order_no": "ORDER-20260920-001",
    "platform_order_no": "PAY202609200001",
    "amount": "100.00",
    "fee_amount": "1.00",
    "settlement_amount": "99.00",
    "channel": "alipay_page",
    "status": 0,
    "notify_status": 0,
    "paid_time": null,
    "settle_time": null,
    "payment_status": "unpaid",
    "payment_status_code": 0,
    "lifecycle_status": "closed",
    "paid_after_closed": false,
    "closed": {
      "closed_at": 1789862400,
      "close_source": "merchant",
      "close_source_id": null,
      "close_reason": "merchant_close",
      "close_message": null
    }
  }
}
说明
  • 关闭已支付订单不会回写为未支付。请同时处理 payment_status 与 lifecycle_status。

创建退款

POST /api/payment/open/v1/refund/create
app_id必填
商户应用 ID。
timestamp必填
Unix 秒级时间戳，与服务端时间误差不得超过 300 秒。
nonce必填
请求唯一随机串，同一 app_id 下不能重放。
sign_type必填
固定为 HMAC-SHA256。
sign必填
应用 secret 对规范化参数串计算出的十六进制 HMAC-SHA256。
platform_order_no
平台订单号。
merchant_order_no
未提供平台订单号时使用的商户订单号。
amount
可选。省略时全额退款，传入时必须等于原订单金额。

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "merchant_order_no": "ORDER-20260920-001",
    "platform_order_no": "PAY202609200001",
    "amount": "100.00",
    "fee_amount": "1.00",
    "settlement_amount": "99.00",
    "channel": "alipay_page",
    "status": 2,
    "notify_status": 0,
    "paid_time": null,
    "settle_time": null,
    "payment_status": "refunded",
    "payment_status_code": 2,
    "lifecycle_status": "active",
    "paid_after_closed": false,
    "closed": null
  }
}
说明
  • 不支持部分退款。refund_no 和 reason 不是当前标准接口消费字段。

状态模型

status
商户订单状态数值: -1 closed、0 unpaid、1 paid、2 refunded、3 refunding。
payment_status
支付状态: unpaid、paid、refunding 或 refunded。
payment_status_code
平台支付状态数值，Open V1 中 -1 仍投影为 payment_status: unpaid。
lifecycle_status
订单生命周期: active 或 closed。
paid_after_closed
订单关闭后才确认到账时为 true，不表示仍允许支付。
closed
生命周期为 closed 时返回关闭快照。

通知与 Webhook

订单支付结果通知

POST notify_url
app_id必填
商户应用 ID。
merchant_order_no必填
商户订单号。
platform_order_no必填
平台订单号。
amount必填
订单金额。
fee_amount必填
商户手续费。
settlement_amount必填
商户结算金额。
status必填
商户订单状态。
paid_time必填
支付时间。
timestamp必填
通知时间戳。
nonce必填
通知随机串。
sign_type必填
HMAC-SHA256。
sign必填
通知签名。
说明
  • 使用 application/x-www-form-urlencoded POST。HTTP 成功且响应正文 trim 后严格等于 success 才算投递成功。

应用生命周期 Webhook

POST webhook_url
event_type必填
payment.succeeded 或 payment.closed。
merchant_order_no必填
商户订单号。
platform_order_no必填
平台订单号。
amount必填
订单金额。
payment_status必填
当前支付状态。
lifecycle_status必填
当前生命周期。
paid_time必填
支付时间。
paid_after_closed必填
是否关闭后到账。
closed
订单关闭时附带关闭快照。
timestamp必填
通知时间戳。
nonce必填
通知随机串。
sign_type必填
HMAC-SHA256。
sign必填
通知签名。
说明
  • 当前 payload 不包含 event_id、app_id、channel 或整数 status。
说明
  • 通知地址必须是可解析的公网 IPv4 地址。失败时平台按重试策略补偿。

Epay 兼容协议

Epay API 下单（mapi）

POST /api/payment/open/epay/mapi
pid必填
Epay 商户应用标识。
type必填
alipay 或 wxpay 等 Epay 支付类型。
out_trade_no必填
商户订单号。
notify_url必填
Epay 异步通知地址。
name必填
商品/订单名称。
money必填
订单金额。
clientip必填
客户端 IP，当前协议要求非空。
sign必填
按 Epay MD5 规则生成的签名。
sign_type
缺省或 md5/MD5，其他类型不支持。
return_url
同步返回地址。
device
pc/desktop 或 mobile/wap/h5 等终端提示，优先于 User-Agent。
param
商户自定义参数。

请求示例

{
  "pid": "PID",
  "type": "alipay",
  "out_trade_no": "EPAY-20260920-001",
  "notify_url": "https://merchant.example/epay/notify",
  "name": "示例订单",
  "money": "100.00",
  "clientip": "203.0.113.10",
  "sign_type": "MD5",
  "sign": "LOWERCASE_MD5"
}

响应示例

{
  "code": 1,
  "msg": "success",
  "O_id": "PAY202609200001",
  "trade_no": "EPAY-20260920-001",
  "payurl": "https://pay.example/checkout/PAY202609200001",
  "payurl2": "https://pay.example/checkout/PAY202609200001",
  "qrcode": "",
  "img": ""
}
说明
  • 同时兼容 /api/payment/open/epay/mapi.php。
  • mapi 响应中的 O_id 是平台订单号，trade_no 是商户订单号。查单响应中的 trade_no 则是平台订单号。
  • payurl/payurl2 是托管 checkout 地址，当前 qrcode 与 img 固定为空。

Epay 页面下单（submit）

POST /api/payment/open/epay/submit
pid必填
Epay 商户应用标识。
type必填
Epay 支付类型。
out_trade_no必填
商户订单号。
notify_url必填
Epay 异步通知地址。
return_url必填
支付完成后的同步返回地址。
name必填
商品/订单名称。
money必填
订单金额。
sign必填
Epay MD5 签名。
说明
  • 同时兼容 /api/payment/open/epay/submit.php 与 GET 请求。
  • submit 成功是 HTTP 302，不是 mapi 的 JSON 响应。托管页最终仍受底层通道配置和就绪状态影响。

Epay 查单与余额

GET /api/payment/open/epay/api[.php]?act=order|balance
pid必填
Epay 商户应用标识。
key必填
商户应用 secret。
act必填
order 或 balance。
out_trade_no
按商户订单号查单。
trade_no
按平台订单号查单。
O_id
平台订单号别名。

响应示例

{
  "code": 1,
  "msg": "success",
  "trade_no": "PAY202609200001",
  "out_trade_no": "EPAY-20260920-001",
  "status": 1
}
说明
  • balance 返回商户 available_balance。Epay code/msg envelope 不等同标准 V1 code/message/data。

Epay 退款

POST /api/payment/open/epay/api[.php]?act=refund
pid必填
Epay 商户应用标识。
key必填
商户应用 secret。
act必填
固定为 refund。
out_trade_no
商户订单号。
trade_no
平台订单号。
money
可选。传入时必须等于原订单金额，不支持部分退款。

响应示例

{
  "code": 1,
  "msg": "退款成功"
}
说明
  • 底层网关不支持自动退款时会返回业务错误。不要把 Epay success 解释为所有通道均已完成退款。

Epay 通知

GET notify_url
pid必填
Epay 商户应用标识。
name必填
订单名称。
money必填
订单金额。
out_trade_no必填
商户订单号。
trade_no必填
平台订单号。
param
商户自定义参数。
trade_status必填
支付成功时为 TRADE_SUCCESS。
type必填
Epay 支付类型。
sign_type必填
MD5。
sign必填
Epay MD5 签名。
说明
  • Epay 异步通知是带签名 query 的 GET，与标准 V1 的 form POST 不同。
  • HTTP 请求成功且响应正文（忽略大小写）包含 success 才算成功。通知会按 Epay 专用策略重试。
  • 原 notify_url 中已有的 query 参数会保留并参与签名。
说明
  • Epay 下单使用 pid + sign 的 MD5 认证。查询、余额和退款使用 pid + key，不使用标准 V1 的 app_id/HMAC 签名。
  • Epay 的 mapi/submit 与标准 V1 的 pay_url、notify_url、webhook_url 不能互换。