Coinpay 支付网关 API 对接文档

快速开始

欢迎使用 Coinpay 支付网关 API。本文档描述了代收（支付）和代付（转账）相关的 API 接口，供第三方平台对接使用。

接入流程

注册商户

联系管理员获取 mchNo（商户号）和 appId（应用ID）

获取密钥

在商户后台获取 appSecret（商户密钥），用于签名计算

对接开发

根据本文档实现 API 调用，注意正确实现签名算法

联调测试

使用本页面的在线测试工具进行接口调试

通用请求参数

所有 API 请求均需包含以下公共参数：

参数名	类型	必填	说明
mchNo	String	必填	商户号
appId	String	必填	商户应用ID
version	String	必填	接口版本号，固定值：`1.0`
signType	String	必填	签名类型，固定值：`MD5`
sign	String	必填	签名值，参见签名算法
reqTime	String	必填	请求时间，13位毫秒时间戳

💡 请求方式 所有接口均使用 POST 方式请求，参数通过 application/x-www-form-urlencoded 格式提交。

JSON 响应结构

{
  "code": 0,        // 0=成功，其他=失败
  "msg": "SUCCESS",  // 状态描述
  "sign": "D6B...",  // 响应签名
  "data": { ... }    // 业务数据
}

签名算法

所有 API 请求和响应均需要进行签名验证，以确保数据安全。

筛选参数

将所有非空参数（排除 sign 本身），按参数名 ASCII 字典序（不区分大小写）排序

拼接字符串

将排序后的参数拼接为 key1=value1&key2=value2&...&key=商户密钥 格式

计算 MD5

对拼接后的字符串做 MD5 运算，将结果转为大写，即为签名值

⚠️ 注意事项

参数值为空的字段不参与签名
sign 字段本身不参与签名
排序不区分大小写（case-insensitive）
最终拼接 key=商户密钥，注意没有尾部 &

假设商户密钥为 abc123，请求参数如下：

原始参数

mchNo=M1234567890
appId=app_001
mchOrderNo=ORDER_001
amount=5000
currency=MXN
wayCode=NOWPAY_SPEI
subject=测试商品
body=商品描述
version=1.0
signType=MD5
reqTime=1708416000000

第1步：排序 + 拼接

amount=5000&appId=app_001&body=商品描述¤cy=MXN&mchNo=M1234567890&mchOrderNo=ORDER_001&reqTime=1708416000000&signType=MD5&subject=测试商品&version=1.0&wayCode=NOWPAY_SPEI&key=abc123

第2步：MD5 → 大写

sign = MD5(拼接字符串).toUpperCase()
     = "A1B2C3D4E5F6..."

币种列表

当前支持的币种如下。请在请求中使用三位 ISO-4217 币种代码。

₱

PHP

菲律宾比索

$

MXN

墨西哥比索

R$

BRL

巴西雷亚尔

¥

CNY

人民币

$

USD

美元

Rp

IDR

印尼盾

₫

VND

越南盾

฿

THB

泰铢

RM

MYR

马来西亚林吉特

₹

INR

印度卢比

支付方式代码（wayCode）

根据不同国家和地区，支持以下支付方式：

🇲🇽 墨西哥（MXN）

wayCode	支付方式	类型
NOWPAY_SPEI	SPEI 银行转账	代收
NOWPAY_OXXO	OXXO 便利店现金	代收
NOWPAY_CASH	现金支付	代收
MX_BANK_CARD	墨西哥银行卡	代付
MX_DIMO	DIMO 转账	代付

🇧🇷 巴西（BRL）

wayCode	支付方式	类型
NOWPAY_BRL_PIX	PIX 即时支付	代收
NOWPAY_BRL_PIX_OUT	PIX 出款	代付

🇵🇭 菲律宾（PHP）

wayCode	支付方式	类型
PH_GCASH	GCash 电子钱包	代收/代付
PH_MAYA	Maya 电子钱包	代收/代付
PH_GOTYME	GoTyme 银行	代收
BANK_CARD	银行卡转账	代付

统一下单

商户通过该接口创建支付订单，获取支付链接或支付参数。

POST /api/pay/unifiedOrder

请求参数

参数名	类型	必填	说明
mchOrderNo	String	必填	商户订单号，需唯一
wayCode	String	必填	支付方式代码，如 `NOWPAY_SPEI`
amount	Long	必填	支付金额，单位：分
currency	String	必填	货币代码，如 `MXN`
subject	String	必填	商品标题
body	String	必填	商品描述信息
clientIp	String	选填	客户端IP地址
notifyUrl	String	选填	异步通知地址（支付成功后回调）
returnUrl	String	选填	页面跳转通知地址
expiredTime	Integer	选填	订单失效时间，单位：秒
channelExtra	String	选填	渠道额外参数（JSON格式）
extParam	String	选填	商户扩展参数，原样返回
divisionMode	Byte	选填	分账模式：0-不分账 1-自动分账 2-手动分账

响应参数

参数名	类型	说明
payOrderId	String	支付系统订单号
mchOrderNo	String	商户订单号
orderState	Integer	订单状态：0-生成 1-支付中 2-成功 3-失败 4-已撤销 6-已关闭
payDataType	String	支付数据类型：payUrl/form/wxapp/codeUrl/codeImgUrl/none
payData	String	支付数据（跳转URL/二维码/表单等）
errCode	String	渠道错误码
errMsg	String	渠道错误描述

JSON 请求体（墨西哥 SPEI）

{
  "mchNo": "M1234567890",
  "appId": "app_001",
  "mchOrderNo": "ORDER_20260330_001",
  "wayCode": "NOWPAY_SPEI",
  "amount": 5000,
  "currency": "MXN",
  "subject": "充值50 MXN",
  "body": "账户充值",
  "notifyUrl": "https://your-site.com/notify",
  "version": "1.0",
  "signType": "MD5",
  "reqTime": "1708416000000",
  "sign": "A1B2C3D4E5F6..."
}

成功响应

{
  "code": 0,
  "msg": "SUCCESS",
  "sign": "D6B7C8A9...",
  "data": {
    "payOrderId": "P1234567890",
    "mchOrderNo": "ORDER_20260330_001",
    "orderState": 1,
    "payDataType": "payurl",
    "payData": "https://pay.example.com/cashier/xxx"
  }
}

在线测试 - 统一下单

查询订单

查询支付订单状态，支持通过商户订单号或系统订单号查询。

POST /api/pay/query

请求参数

参数名	类型	必填	说明
payOrderId	String	二选一	支付系统订单号
mchOrderNo	String	二选一	商户订单号

💡 提示 payOrderId 和 mchOrderNo 不能同时为空，至少传一个。

响应参数

参数名	类型	说明
payOrderId	String	支付系统订单号
mchOrderNo	String	商户订单号
state	Integer	订单状态：0-生成 1-支付中 2-成功 3-失败 4-已撤销 6-已关闭
ifCode	String	支付接口代码
wayCode	String	支付方式代码
amount	Long	支付金额（分）
currency	String	货币代码
successTime	Long	支付成功时间（时间戳）

在线测试 - 查询订单

关闭订单

关闭未支付的订单，仅支持订单状态为"生成"或"支付中"的订单。

POST /api/pay/close

请求参数

参数名	类型	必填	说明
payOrderId	String	二选一	支付系统订单号
mchOrderNo	String	二选一	商户订单号

在线测试 - 关闭订单

支付回调通知

当支付成功后，系统将向商户配置的 notifyUrl 发送异步通知。

💡 回调机制

通知方式：POST 请求 + application/x-www-form-urlencoded
通知频率：支付成功后立即通知，失败后间隔 30s、1min、5min、30min 重试
成功标识：商户响应 HTTP 200 且内容为 success 即视为通知成功
签名验证：通知参数中包含 sign，商户需验证签名

通知参数

参数名	类型	说明
payOrderId	String	支付系统订单号
mchNo	String	商户号
appId	String	应用ID
mchOrderNo	String	商户订单号
ifCode	String	支付接口代码
wayCode	String	支付方式代码
amount	Long	支付金额（分）
currency	String	货币代码
state	Integer	订单状态：2=成功
successTime	Long	支付成功时间
sign	String	签名值

⚠️ 重要 收到通知后必须验证签名，并响应字符串 success（注意小写），否则系统将持续重发。

发起转账

商户通过该接口发起代付（转账）请求，将资金转入指定账户。

POST /api/transferOrder

请求参数

参数名	类型	必填	说明
mchOrderNo	String	必填	商户订单号
ifCode	String	必填	支付接口代码
entryType	String	必填	入账方式，参见下方说明
amount	Long	必填	转账金额，单位：分
currency	String	必填	货币代码，如 `MXN`、`BRL`、`PHP`
accountNo	String	必填	收款账号
accountName	String	选填	收款人姓名
bankName	String	选填	收款人开户行名称
clientIp	String	选填	客户端IP地址
transferDesc	String	必填	转账备注信息
notifyUrl	String	选填	异步通知地址
channelExtra	String	选填	渠道额外参数（JSON格式）
extParam	String	选填	商户扩展参数

入账方式（entryType）说明

entryType	适用国家	说明
BANK_CARD	通用	银行卡转账
MX_BANK_CARD	🇲🇽 墨西哥	墨西哥银行卡（CLABE）
MX_DIMO	🇲🇽 墨西哥	DIMO 即时转账
NOWPAY_BRL_PIX_OUT	🇧🇷 巴西	PIX 出款
PH_GCASH	🇵🇭 菲律宾	GCash 电子钱包
PH_MAYA	🇵🇭 菲律宾	Maya 电子钱包

💡 墨西哥代付说明

转账限额：最低 40 MXN，最高 15,000 MXN
accountNo 填写 CLABE 号码（18位）或银行卡号
ifCode 填写 nowpay

💡 巴西代付说明

accountNo 填写 PIX Key（CPF/CNPJ/邮箱/手机号/随机密钥）
ifCode 填写 nowpay

响应参数

参数名	类型	说明
transferId	String	转账系统订单号
mchOrderNo	String	商户订单号
state	Integer	状态：0-生成 1-处理中 2-成功 3-失败
channelOrderNo	String	渠道订单号
errCode	String	错误码
errMsg	String	错误描述

在线测试 - 发起转账

查询转账

查询转账订单状态。

POST /api/transfer/query

请求参数

参数名	类型	必填	说明
transferId	String	二选一	转账系统订单号
mchOrderNo	String	二选一	商户订单号

在线测试 - 查询转账

转账回调通知

转账完成后，系统将向商户配置的 notifyUrl 地址发送异步通知。

通知参数

参数名	类型	说明
transferId	String	转账系统订单号
mchNo	String	商户号
appId	String	应用ID
mchOrderNo	String	商户订单号
amount	Long	转账金额（分）
currency	String	货币代码
state	Integer	转账状态：2=成功 3=失败
sign	String	签名值

💡 响应规范 商户收到通知后，验证签名成功请响应 success 字符串。

PayPH 兼容 API — 说明

💡 兼容模式 本平台额外提供一套兼容 PayPH 格式的 API 接口。如果您之前对接的是 PayPH 平台，只需将 网关地址 改为 https://ccoinpay.org，并将 parter 设为本平台分配的 AppID、key 设为对应的 AppSecret，即可无缝迁移，无需修改其他代码。

兼容端点与原有 Coinpay API 并行运行，互不影响。下方为各端点说明。

端点	方法	说明
/payment/create	POST	发起代收（下单）
/pay/query	POST	代收订单查询
/pay/transfer	POST	发起代付（转账）
/pay/transfer/query	POST	代付查询 V1
/pay/transfer/query/detail	POST	代付查询 V2（详情）
/payment/query/balance	POST	商户余额查询
/pay/transfer/receipt	POST	获取代付凭证

PayPH 兼容 — 签名规则

签名算法与 PayPH 完全一致：

将所有非空参数（不含 sign、不含 clientip、不含 attach）按参数名 ASCII 升序排列
拼接为 key1=value1&key2=value2&...&key=YOUR_SECRET
对拼接字符串计算 MD5，结果转为小写

⚠️ 与 Coinpay 原生签名的区别
PayPH 兼容接口的 MD5 结果为小写（Coinpay 原生为大写）。

签名示例（PHP）

$params = [
    'parter'    => '699ac3a959be3e4c538a2034',
    'value'     => '100.00',
    'type'      => 'GcashWap',
    'orderid'   => 'T20260222001',
    'notifyurl' => 'https://your-site.com/callback',
];
ksort($params, SORT_FLAG_CASE | SORT_STRING);
$str = '';
foreach ($params as $k => $v) {
    if ($v !== '') $str .= "$k=$v&";
}
$str .= 'key=' . $secret;
$sign = md5($str); // 小写

发起代收 — POST /payment/create

POST /payment/create

请求参数

参数名	必填	说明
parter	是	商户 AppID
value	是	金额（元），如 `100.00`
type	是	支付类型：`GcashWap`、`Maya`、`Gotyme`
orderid	是	商户订单号
notifyurl	否	异步通知地址
callbackurl	否	前端跳转地址
clientip	否	客户端IP（不参与签名）
attach	否	附加参数（不参与签名，回调原样返回）
sign	是	签名值（MD5 小写）

响应示例

{
    "code": 200,
    "info": "success",
    "param": {
        "payment_url": "https://pay.example.com/cashier/xxxx"
    }
}

代收查询 — POST /pay/query

POST /pay/query

请求参数

参数名	必填	说明
parter	是	商户 AppID
orderid	是	商户订单号

state 值：100=处理中，200=支付成功，400=支付失败

响应示例

{
    "code": "200",
    "state": "200",
    "msg": "支付成功",
    "price": "100.00"
}

发起代付 — POST /pay/transfer

POST /pay/transfer

请求参数

参数名	必填	说明
parter	是	商户 AppID
order_no	是	商户订单号
type	是	入账方式：`PH_GCASH`、`PH_MAYA`、`BANK_CARD`
name	否	收款人姓名
account_number	是	收款账号
money	是	金额（元），如 `100.00`
notify_url	否	异步通知地址
sign	是	签名值（MD5 小写）

响应示例

{
    "code": "200",
    "info": "提交成功"
}

代付查询 — POST /pay/transfer/query

POST /pay/transfer/query

V2 详细版：POST /pay/transfer/query/detail

请求参数

参数名	必填	说明
parter	是	商户 AppID
order_no	是	商户订单号

status 值：1=未处理，2=处理中，3=已支付，4=支付失败

V1 响应示例

{
    "code": "200",
    "info": "success",
    "param": {
        "status": 3,
        "price": "100.00"
    }
}

V2 响应示例（detail）

{
    "code": 200,
    "info": "success",
    "param": {
        "status": 3,
        "price": "100.00",
        "fee": "0.00",
        "uporder": "CH20260222001",
        "completion_time": "2026-02-22 19:00:00"
    }
}

商户余额 — POST /payment/query/balance

POST /payment/query/balance

请求参数

参数名	必填	说明
parter	是	商户 AppID

响应示例

{
    "code": 200,
    "info": "success",
    "param": {
        "balance": "5000.00"
    }
}

PayPH 兼容 — 回调通知

通过 PayPH 兼容接口创建的订单，回调通知也将采用 PayPH 格式：

代收回调参数

参数名	说明
parter	商户 AppID
orderid	商户订单号
opstate	状态：`1`=成功，`0`=失败
ovalue	金额（元）
sign	签名（MD5 小写）

代付回调参数（额外增加 remark 字段）

参数名	说明
parter	商户 AppID
orderid	商户订单号
opstate	状态：`1`=成功，`0`=失败
ovalue	金额（元）
remark	备注信息
sign	签名（MD5 小写）

回调签名验证

固定字段顺序：opstate={X}&orderid={X}&ovalue={X}&parter={X}&key={SECRET} → MD5 小写

💡 回调响应 收到回调后，商户应返回字符串 opstate=0 表示已成功接收。否则系统将持续重试通知。

错误码

以下为支付网关可能返回的错误码：

错误码	说明	处理建议
0	请求成功	正常处理
9999	系统异常	联系技术支持
10	参数校验失败	检查请求参数
11	参数格式错误	检查参数格式（如缺少必填字段）
12	签名验证失败	检查签名算法及密钥
15	数据不存在	检查商户号/订单号是否正确
20	系统繁忙	稍后重试
25	订单不存在	检查订单号
30	商户不存在或已停用	联系管理员
35	应用不存在或已停用	检查 appId
40	支付通道不可用	更换支付方式或联系管理员
45	不支持的支付方式	检查 wayCode
50	不支持的货币	检查 currency
55	订单已关闭	重新创建订单

💡 错误处理 当 code != 0 时，msg 字段会包含具体的错误描述信息。建议在业务逻辑中同时判断 code 和 msg。