Convenient Pay 接口说明

概览

开放接口数 5

支持方式 JSON POST

时效要求 5 分钟签名时窗

所有接口都走 POST，请求头使用 Content-Type: application/json。
开放接口推荐通过 https://openapi.cpaynow.com/v1/... 访问。
签名字段统一叫 sign，签名原文按字段名升序拼接后追加商户密钥。
时间戳支持秒或毫秒，但服务端仅接受与当前时间差不超过 5 分钟的请求。
所有示例均使用 JSON 请求体，可直接作为联调样例参考。

建议所有商户统一使用 openapi.cpaynow.com 作为开放接口网关。

签名规则

签名逻辑与当前后端实现一致：

排除字段 sign。
过滤所有空值、null、undefined、空字符串。
按字段名升序排序。
拼成 key=value&key=value。
最后在尾部追加 &merchantSecret。
对整个字符串做 MD5，输出小写 32 位字符串。

amount=100.00&currency=VND&merchant_no=M10001&notify_url=https://merchant.example.com/notify&product_no=P10001&timestamp=1760000000000&trade_no=T202603210001&version=v1&merchantSecret

代收与代付下单的签名字段不完全相同，建议严格按请求体真实字段参与签名，不要把未传字段补空再签。

代收下单

POST /v1/trade/payin

创建一笔代收订单，成功后返回收银台链接。

字段	必填	说明
merchant_no	是	商户编号
trade_no	是	商户订单号，需唯一
amount	是	金额文本，如 100.00
currency	是	币种，当前支持 VND / CNY
product_no	是	商户绑定的代收产品号
notify_url	是	异步回调地址，仅支持公网 http/https
timestamp	是	秒或毫秒时间戳
member_name	是	会员姓名
return_url	否	同步跳转地址
extra	否	透传字段
ip	否	用户 IP
identity_no	否	身份标识
version	否	默认且仅支持 v1
sign	是	签名值

{
  "merchant_no": "M10001",
  "trade_no": "COL202603210001",
  "amount": "100.00",
  "currency": "VND",
  "product_no": "COLLECT_VND",
  "notify_url": "https://merchant.example.com/notify",
  "timestamp": "1760000000000",
  "member_name": "Nguyen Van A",
  "version": "v1",
  "sign": "md5sign"
}

{
  "platform_trace_no": "PT17740000000000001",
  "trade_no": "COL202603210001",
  "merchant_no": "M10001",
  "product_no": "COLLECT_VND",
  "currency": "VND",
  "amount": "100.00",
  "order_time": "2026-03-21 19:35:40",
  "url": "https://top1.cpaynow.com/pay?token=xxxx",
  "status": "1"
}

代付下单

POST /v1/trade/payout

创建一笔代付订单，成功后返回平台单号和 deeplink 信息。

字段	必填	说明
merchant_no	是	商户编号
trade_no	是	商户订单号，需唯一
amount	是	金额文本
currency	是	VND / CNY
product_no	是	代付产品号
notify_url	是	回调地址
timestamp	是	秒或毫秒时间戳
account	是	收款账号
account_type	是	当前仅支持 BANK
payee	是	收款人姓名
bank	是	银行名称
bank_code	VND 必填	越南银行编码
bank_branch	否	支行名称
remark	否	备注
extra	否	透传字段
sign	是	签名值

{
  "merchant_no": "M10001",
  "trade_no": "PO202603210001",
  "amount": "2000.00",
  "currency": "VND",
  "product_no": "PAYOUT_VND",
  "notify_url": "https://merchant.example.com/notify",
  "timestamp": "1760000000000",
  "account": "0123456789",
  "account_type": "BANK",
  "payee": "Tran Thi B",
  "bank": "ACB",
  "bank_code": "970416",
  "bank_branch": "HCM Branch",
  "version": "v1",
  "sign": "md5sign"
}

{
  "platform_trace_no": "PT17740000000000002",
  "trade_no": "PO202603210001",
  "merchant_no": "M10001",
  "product_no": "PAYOUT_VND",
  "currency": "VND",
  "amount": "2000.00",
  "order_time": "2026-03-21 19:36:10",
  "fee": "0.00",
  "status": "1",
  "deeplink_url": "bank-app://transfer?..."
}

订单查询

代收查询

POST /v1/payin/query

代付查询

POST /v1/payout/query

两个查询接口请求体结构一致：

{
  "merchant_no": "M10001",
  "trade_no": "COL202603210001",
  "currency": "VND",
  "timestamp": "1760000000000",
  "sign": "md5sign"
}

返回示例：

{
  "platform_trace_no": "PT17740000000000001",
  "merchant_no": "M10001",
  "trade_no": "COL202603210001",
  "amount": "100.00",
  "currency": "VND",
  "status": "2",
  "success_time": "2026-03-21 19:40:12"
}

余额查询

POST /v1/balance/query

{
  "merchant_no": "M10001",
  "currency": "CNY",
  "timestamp": "1760000000000",
  "sign": "md5sign"
}

{
  "merchant_no": "M10001",
  "mch_name": "Demo Merchant",
  "currency": "CNY",
  "balance": "0.00",
  "freeze": "0.00"
}

回调说明

代收成功、代付成功、代付失败都会向商户的 notify_url 发起 JSON POST 回调。

{
  "merchant_no": "M10001",
  "trade_no": "PO202603210001",
  "platform_trace_no": "PT17740000000000002",
  "amount": "2000.00",
  "currency": "VND",
  "status": "3",
  "timestamp": "1760000020000",
  "order_type": "PAYOUT",
  "sign": "md5sign"
}

status=1 表示处理中 / 待处理。
status=2 表示成功。
status=3 表示失败。

当前系统会校验 notify_url 的公网可达性，不允许私网 IP、空 host、非法协议。测试默认地址可做 mock 成功，但正式接入不要使用默认测试地址。

状态与错误码

值	含义
1	处理中 / PENDING
2	成功 / SUCCESS
3	失败 / FAILED

常见错误

missing required fields：缺少必填参数。
timestamp invalid：时间戳格式错误。
timestamp expired：时间戳超过 5 分钟。
sign invalid：签名校验失败。
merchant is disabled：商户未启用。
trade_no already exists：商户订单号重复。
bank_code is required when currency is VND：VND 代付未传银行编码。

开放平台接口文档

概览

签名规则

代收下单

代付下单

订单查询

代收查询

代付查询

余额查询

回调说明

状态与错误码

常见错误