CoinPay · 代收付 API 文档

01 SECTION

响应格式说明

所有 API 响应均采用统一的 JSON 格式。响应结果通过 code 字段标识业务执行状态，成功响应携带 data 业务数据，失败响应携带 message 错误信息。

200 OK 成功响应

{
  "code": "0",
  "message": "Success",
  "data": { ... }
}

FAIL 失败响应

{
  "code": "-1",
  "message": "错误信息"
}

字段说明

code 字段为字符串类型，成功时为 "0"，失败时为 "-1" 或其他错误码
data 字段仅在成功响应时存在，失败响应不包含此字段
响应不包含 timestamp 字段

【代付】特别说明：代付申请响应 code 为 -1 仅代表「请求流程失败」，并非「代付订单失败」。此情况下订单状态需人工核实后再行通知，请勿自行处理为订单失败。

02 SECTION

回调通知说明

系统会在订单状态变更时，主动向商户发送回调通知。商户需要提供回调接口来接收这些通知，并依照签名规则完成验签后再更新本地订单状态。

签名验证

所有回调通知都会包含 signature 参数，商户需要验证签名以确保回调来自本系统。

签名生成规则

参数排序

将所有参数（排除 signature、callbackUrl、extend）按照 key 的 A-Z 顺序排序。

拼接字符串

使用 key=value 格式，用 & 符号拼接，value 需要 urlencode 转义。

追加密钥

在拼接字符串后面加上商户的 MD5 Key。

MD5 加密

对整个字符串进行 MD5 加密。

空值处理

空字符串或 null 的 key 也需要一并加入验签。

不参与签名计算的参数： signature（签名本身）、callbackUrl（回调通知 URL）、extend（商户端附加信息）。

签名示例

生成步骤演示

原始参数：merchantNo=TEST_MERCHANT, orderNo=SYS20250905113800, amount=100.00, callbackUrl=https://..., extend=附加信息

① 排序后（已排除 callbackUrl、extend）：

STEP 1 · SORTED

amount=100.00&merchantNo=TEST_MERCHANT&orderNo=SYS20250905113800

② 加上 Key：

STEP 2 · APPEND KEY

amount=100.00&merchantNo=TEST_MERCHANT&orderNo=SYS20250905113800{MD5_KEY}

③ MD5 加密：

STEP 3 · MD5

md5(amount=100.00&merchantNo=TEST_MERCHANT&orderNo=SYS20250905113800{MD5_KEY})

完整示例

JSON · REQUEST PARAMETERS

{
  "merchantNo": "TEST_MERCHANT",
  "merchantOrder": "WDR20250905113800",
  "channel": "BANK_CARD",
  "amount": "100.00",
  "currency": "PHP",
  "bankCode": "PH_GCASH",
  "bankAccountName": "David Chen",
  "bankAccountNo": "6222020000000000000",
  "bankBranch": "GCASH",
  "dateTime": "250905113800",
  "callbackUrl": "https://your.domain/callback",
  "extend": "附加信息"
}

API Key：c96a632498a1cfe803e46625c9a8bc08

生成签名前字符串（注意 bankAccountName 中的空格会被转义为 +）：

BEFORE MD5

amount=100.00&bankAccountName=David+Chen&bankAccountNo=6222020000000000000&bankBranch=GCASH&bankCode=PH_GCASH&channel=BANK_CARD¤cy=PHP&dateTime=250905113800&merchantNo=TEST_MERCHANT&merchantOrder=WDR20250905113800c96a632498a1cfe803e46625c9a8bc08

生成 MD5 签名：6de50bec329e43799984016b63e93be3

验签工具

提供在线验签工具便于调试：/signature-validator.html

PHP 示例代码

PHP

function generateSignature(array $params, string $key): string
{
    // 移除不需要参与签名的字段
    unset($params['extend']);
    unset($params['callbackUrl']);
    unset($params['signature']);

    ksort($params); // 按 key 升序排序
    $parts = [];
    foreach ($params as $k => $v) {
        $parts[] = $k . '=' . urlencode((string)$v);
    }
    $beforeGenSignStr = implode('&', $parts);
    $beforeGenSignStr .= $key;
    return md5($beforeGenSignStr);
}

03 ENDPOINT

代收申请

商户发起代收订单请求。系统受理后会返回支付链接或二维码地址，引导付款人完成支付。

POST /deposit/apply

请求参数 Content-Type: application/json

参数	类型	说明
merchantNo必填	string	商户代码
merchantOrder必填	string	商户订单号
channel必填	string	渠道代码，请参考支持列表
amount必填	string<decimal>	交易金额，单位：元，小数 2 位
currency必填	string	币种，固定值 `"PHP"`
dateTime必填	string<ymdHis>	日期时间
signature必填	string	签名字符串
payerName选填	string	付款人姓名
callbackUrl必填	string<uri>	回调通知 URL
extend选填	string	商户端附加信息
version选填	string	API 版本号，固定写入 `V1.1`

请求示例

JSON · REQUEST BODY

{
  "merchantNo": "TEST_MERCHANT",
  "merchantOrder": "DEP20250905113800",
  "channel": "QRPH_GCASH",
  "amount": "100.00",
  "currency": "PHP",
  "dateTime": "250905113800",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "payerName": "David Chen",
  "callbackUrl": "https://your.domain/callback",
  "extend": "附加信息",
  "version": "V1.1"
}

响应示例

JSON · 200 OK

{
  "code": "0",
  "message": "Success",
  "data": {
    "system_order_no": "system_order_no",
    "provider_order_no": "provider_order_no",
    "amount": 100,
    "url": "https://www.example.com/pay/qr_pay?token=SDRIQA320251215204037152"
  }
}

JSON · 422 VALIDATION ERROR

{
  "code": "-1",
  "message": "参数验证失败"
}

04 ENDPOINT

代收回调通知

此接口由商户实现，系统会主动调用。当代收订单状态变更时，系统会向商户提供的 callbackUrl 发送 POST 请求。

POST /merchant/callback/deposit

接收流程

接收回调

商户需实现一个 POST 接口来接收回调通知。

验证签名

使用商户 MD5 Key 验证 signature 参数（验证规则请参考首页签名验证说明）。

处理业务

根据订单状态更新商户系统的订单状态。

返回响应

返回 HTTP 200-299 状态码，响应内容必须包含 success 字符串（不区分大小写）。例如：JSON {"code": 0, "message": "success"} 或直接返回文字 success。

重试机制：如果商户端返回非 200-299 状态码或响应内容未包含 success 字符串，系统会重试最多 5 次，重试间隔 60 秒。建议商户端实现幂等性处理。

回调参数

参数	类型	说明
type必填	string	交易类型：`deposit`
orderNo必填	string	系统订单号
merchantNo必填	string	商户代码
order_amount必填	string	订单金额，单位：元，小数 2 位
actual_amount必填	string	实际到账金额，单位：元，小数 2 位
currency必填	string	币种
merchantOrder必填	string	商户订单号
status必填	integer	订单状态：`0`=未处理 / `1`=处理中 / `3`=失败 / `4`=成功
successTime可空	string	成功时间（nullable）
extend可空	string	商户端附加信息（nullable）
providerOrderDetailNo选填	string	六码单号（申请时 version 填入 V1.1 才返回）
signature必填	string	签名字符串

回调请求示例

JSON · CALLBACK BODY

{
  "type": "deposit",
  "orderNo": "SYS20250905113800",
  "merchantNo": "TEST_MERCHANT",
  "order_amount": "100.00",
  "actual_amount": "100.00",
  "currency": "PHP",
  "merchantOrder": "DEP20250905113800",
  "status": 4,
  "successTime": "2025-09-05 11:57:20",
  "extend": "附加信息",
  "providerOrderDetailNo": "123456",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

商户响应示例

JSON · 200 OK

{
  "code": 0,
  "message": "success"
}

05 ENDPOINT

代收查询

主动查询某笔代收订单的当前状态与处理详情。

POST /deposit/query

请求参数

参数	类型	说明
merchantNo必填	string	商户代码
merchantOrder必填	string	商户订单号
dateTime必填	string<ymdHis>	日期时间
signature必填	string	签名字符串

请求示例

JSON · REQUEST BODY

{
  "merchantNo": "TEST_MERCHANT",
  "merchantOrder": "DEP20250905113800",
  "dateTime": "250905113800",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

响应示例

JSON · 200 OK

{
  "code": "0",
  "message": "Success",
  "data": {
    "type": "deposit",
    "orderNo": "orderNo",
    "merchantNo": "merchantNo",
    "order_amount": "200.00",
    "actual_amount": "200.00",
    "currency": "PHP",
    "merchantOrder": "merchantOrder",
    "status": 4,
    "successTime": "2025-12-15 15:28:05",
    "extend": null,
    "providerOrderDetailNo": "123456",
    "signature": "c4701e72a5c59bcf2fb010ad685d57ea"
  }
}

06 ENDPOINT

代付申请

商户向指定的收款银行账户发起代付请求。系统受理后将订单进入处理流程，并通过回调通知最终结果。

重要注意事项
· 代付申请一旦提交，若未收到明确成功时，请联系客服询问，避免重复出款。
· 请求超时，请勿列为失败订单，请联系客服询问。
· HTTP 5XX 状态都是发生在双方网络沟通异常，请勿列为失败订单。

POST /withdraw/apply

请求参数

参数	类型	说明
merchantNo必填	string	商户代码
merchantOrder必填	string	商户订单号
channel必填	string	渠道代码，请参考支持列表
amount必填	string<decimal>	交易金额，单位：元，小数 2 位
currency必填	string	币种，固定值 `"PHP"`
bankCode必填	string	收款人银行代码，请参考支持列表
bankAccountName必填	string	收款人银行卡姓名
bankAccountNo必填	string	收款人银行卡卡号
bankBranch选填	string	收款人银行支行
dateTime必填	string<ymdHis>	日期时间
signature必填	string	签名字符串
callbackUrl必填	string<uri>	回调通知 URL
extend选填	string	商户端附加信息
version选填	string	API 版本号，填入 `V1.1` 时回调及查询会多返回 providerReferenceNo

请求示例

JSON · REQUEST BODY

{
  "merchantNo": "TEST_MERCHANT",
  "merchantOrder": "WDR20250905113800",
  "channel": "BANK_CARD",
  "amount": "100.00",
  "currency": "PHP",
  "bankCode": "PH_GCASH",
  "bankAccountName": "David Chen",
  "bankAccountNo": "6222020000000000000",
  "bankBranch": "GCASH",
  "dateTime": "250905113800",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "callbackUrl": "https://your.domain/callback",
  "extend": "附加信息",
  "version": "V1.1"
}

响应示例

JSON · 200 OK

{
  "code": "0",
  "message": "Success",
  "data": {
    "merchant_order_no": "merchant_order_no",
    "system_order_no": "system_order_no",
    "provider_order_no": "provider_order_no",
    "amount": 100,
    "order_status": 0
  }
}

07 ENDPOINT

代付回调通知

此接口由商户实现，系统会主动调用。当代付订单状态变更（成功 / 失败 / 处理中）时，系统会向 withdrawApply 时提供的 callbackUrl 发送 POST 请求。

POST /merchant/callback/withdraw

接收流程

接收回调

商户需实现一个 POST 接口来接收回调通知。

验证签名

使用商户 MD5 Key 验证 signature 参数。

处理业务

根据订单状态更新商户系统的订单状态。

返回响应

返回 HTTP 200-299 状态码，响应内容必须包含 success 字符串。

重试机制：如果商户端返回非 200-299 状态码或响应内容未包含 success 字符串，系统会重试最多 5 次，重试间隔 60 秒。建议商户端实现幂等性处理。

回调参数

参数	类型	说明
type必填	string	交易类型：`withdraw`
orderNo必填	string	系统订单号
merchantNo必填	string	商户代码
amount必填	string	代付金额，单位：元，小数 2 位
currency必填	string	币种
merchantOrder必填	string	商户订单号
status必填	string	订单状态：`0`=未处理中 / `1`=处理中 / `3`=失败 / `4`=成功
successTime可空	string	成功时间（nullable）
extend可空	string	商户端附加信息（nullable）
message可空	string	返还消息（nullable）
providerReferenceNo选填	string	参考号（申请时 version 填入 V1.1 才返回）
signature必填	string	签名字符串

回调请求示例

JSON · CALLBACK BODY

{
  "type": "withdraw",
  "orderNo": "SYS20250905113800",
  "merchantNo": "TEST_MERCHANT",
  "amount": "100.00",
  "currency": "PHP",
  "merchantOrder": "WDR20250905113800",
  "status": "3",
  "successTime": "2025-09-05 11:57:20",
  "extend": "附加信息",
  "message": "AC01-IncorrectAccountNumber",
  "providerReferenceNo": "123456",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

商户响应示例

JSON · 200 OK

{
  "code": 0,
  "message": "success"
}

08 ENDPOINT

代付查询

主动查询某笔代付订单的当前状态与处理详情。

POST /withdraw/query

请求参数

参数	类型	说明
merchantNo必填	string	商户代码
merchantOrder必填	string	商户订单号
dateTime必填	string<ymdHis>	日期时间
signature必填	string	签名字符串

请求示例

JSON · REQUEST BODY

{
  "merchantNo": "TEST_MERCHANT",
  "merchantOrder": "WDR20250905113800",
  "dateTime": "250905113800",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

响应示例

JSON · 200 OK

{
  "code": "0",
  "message": "Success",
  "data": {
    "type": "withdraw",
    "orderNo": "orderNo",
    "merchantNo": "merchantNo",
    "amount": "100.00",
    "currency": "PHP",
    "merchantOrder": "merchantOrder",
    "status": 3,
    "successTime": "2025-12-15 15:31:10",
    "extend": null,
    "message": "AC01-IncorrectAccountNumber",
    "providerReferenceNo": "123456",
    "signature": "0f5308ae44ba2922ff21ad3a7147f28b"
  }
}

09 ENDPOINT

余额查询

查询商户账户的可用余额、冻结余额及总余额。

POST /balance/query

请求参数

参数	类型	说明
merchantNo必填	string	商户代码
dateTime必填	string<ymdHis>	日期时间
signature必填	string	签名字符串

请求示例

JSON · REQUEST BODY

{
  "merchantNo": "TEST_MERCHANT",
  "dateTime": "250905113800",
  "signature": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

响应示例

JSON · 200 OK

{
  "code": "0",
  "message": "Success",
  "data": {
    "available_balance": "10000.00",
    "hold_balance": "0.00",
    "total_balance": "10000.00"
  }
}

10 REFERENCE

支持列表

系统支持的支付渠道与银行列表（参考资料）。

支付渠道

用于代收 / 代付申请时的 channel 参数。

GET /reference/payment-channels

类型	渠道代码	渠道名称
代收	QRPH_GCASH	GCashQR
代收	GCASH	GCash
代收	GRAB_PAY	Grab Pay
代收	PAYMAYA	Paymaya
代付	BANK_CARD	Bank Card

支持银行

用于代付申请时选择收款银行的 bankCode 参数。

GET /reference/banks

PHILIPPINES BANK CODES 87 ENTRIES

PH_BRBBinangonan Rural Bank (BRBDigital)

PH_AUBAsia United Bank Corporation

PH_BDOBDO Unibank

PH_BCHBank of China

PH_LBPLANDBANK / OFBank

PH_APYAlipay / Lazada Wallet

PH_METMetropolitan Bank and Trust Co.

PH_BPIBPI / BPI Family Savings Bank

PH_CPICIMB Philippines, Inc.

PH_CISBayad

PH_CCBCTBC Bank (Philippines) Corporation

PH_DCPCoins.ph (DCPay)

PH_DBIDungganon Bank (A Microfinance Rural Bank), Inc.

PH_EWRKomo / EastWest Rural Bank

PH_EWBEast West Banking Corporation

PH_GOTGoTyme Bank

PH_GCASHGCash

PH_IEMInfoserve / Nationlink

PH_IRII-Remit / iCASH

PH_ISLISLA Bank (A Thrift Bank), Inc.

PH_SEASeabank

PH_MSBMalayan Bank Savings and Mortgage Bank, Inc.

PH_MCBMindanao Consolidated CoopBank

PH_MYAMaya Bank, Inc.

PH_OPIOmniPay, Inc.

PH_ALBALLBANK INC

PH_PPSPalawanPay

PH_PARPartner Rural Bank (Cotabato), Inc.

PH_PRBProducers Bank

PH_RCIRCBC/DiskarTech

PH_CMGCamalig Bank

PH_SPPShopeePay

PH_SPYStarpay

PH_TCITayoCash

PH_TDBTonik Bank

PH_UNOUNObank

PH_UDBUnionDigital Bank

PH_UMSUSSC Money Services

PH_WDBWealth Development Bank

PH_ZTIJuanCash (Zybi Tech Inc.)

PH_CRDCARD Bank Inc.

PH_SMECARD SME Bank

PH_DBPDevelopment Bank of the Philippines

PH_UBPUnion Bank of the Philippines

PH_SCBStandard Chartered Bank

PH_TPITraxionPay/DigiCOOP/COOPNET

PH_SSBSun Savings Bank, Inc.

PH_SBASterling Bank of Asia, Inc (A Savings Bank)

PH_MPIMaybank Philippines, Inc.

PH_PBCPhilippine Bank of Communications

PH_PNBPhilippine National Bank (PNB)

PH_SECSecurity Bank Corporation

PH_EQBEquicom Savings Bank, Inc.

PH_PSBPhilippine Savings Bank

PH_RBNRobinsons Bank Corporation

PH_UCPUnited Coconut Planters Bank (UCPB)

PH_USBUCPB Savings Bank

PH_PPIPayMaya Philippines, Inc.

PH_PVBPhilippine Veterans Bank

PH_INGING Bank N.V.

PH_QRBQuezon Capital Rural Bank

PH_BMBBangko Mabuhay

PH_CBSChina Bank Savings, Inc.

PH_BOCBank of Commerce

PH_CBCChina Banking Corporation

PH_CLBCebuana Lhuillier Bank / Cebuana Xpress

PH_ONBBDO Network Bank

PH_DCBDumaguete City Development Bank

PH_ERBEntrepreneur Rural Bank, Inc./ENTRP

PH_LSBLegazpi Savings Bank

PH_LDBLuzon Development Bank

PH_PASPacific Ace Savings Bank

PH_PBBPhilippine Business Bank, Inc., A Savings Bank

PH_QCBQueenbank

PH_NBKNetbank

PH_RBGAsenso

PH_BGBBanKo, A Subsidiary of BPI

PH_GBYGrabPay

PH_PTCPhilippine Trust Company

PH_PMGPayMongo Payments Inc

PH_CBICANTILAN BANK, INC.

PH_MCPMARCOPAY INC

PH_CSVCity Savings Bank

PH_EPGEasy Pay Global EMI Corp

PH_OWBOwn Bank

PH_PDXPDAX / PhilDigitalAssetExchange

PH_SPDSpeedyPay

代收付 API支付网关接口

响应格式说明

字段说明

回调通知说明

签名验证

签名生成规则

签名示例

生成步骤演示

完整示例

验签工具

PHP 示例代码

代收申请

请求参数 Content-Type: application/json

请求示例

响应示例

代收回调通知

接收流程

回调参数

回调请求示例

商户响应示例

代收查询

请求参数

请求示例

响应示例

代付申请

请求参数

请求示例

响应示例

代付回调通知

接收流程

回调参数

回调请求示例

商户响应示例

代付查询

请求参数

请求示例

响应示例

余额查询

请求参数

请求示例

响应示例

支持列表

支付渠道

支持银行

代收付 API
支付网关接口