API付款

全球付款

API付款

通过 API 直接发起付款请求，适用于单笔即时提现或大批量向各地不同收款人付款的场景。本文档涵盖集成准备、交互流程、接口列表及集成步骤。

集成准备

1.1

商务洽谈

与 PayCools 完成商务洽谈后，在技术对接群中提供您的 商户名称 和邮箱，技术支持会将账号信息发送到您的邮箱。

1.2

技术参数配置

登录商户后台，完成以下配置：

公钥配置：生成 RSA 密钥对（2048 位），在商户后台上传商户公钥，获取平台公钥。详见技术参数配置(公钥配置)
获取 AppID：在应用详情页面获取 AppID，用于调用 PayCools API
配置代付回调地址：在 API Key 页面配置代付结果通知地址（Notify URL），平台在代付交易状态变更时会向该地址发送异步通知
查看环境信息：查看环境信息，获取不同环境的请求地址和平台公钥

1.3

签名与验签

理解请求报文加签和验签的原理，详见配置与签名，用于生成每次 HTTP 请求 Header 的 sign 签名字符串。

交互流程

付款 — 成功下单

付款 — 下单失败

交易状态查询

接口列表

代付代付下单接口商户 → PayCools

查看文档

代付查询代付状态接口商户 → PayCools

查看文档

代付代付结果回调通知PayCools → 商户

该接口由商户实现，作用是在用户完成还款交易时，调用此接口将还款交易详情通知给商户。

查看文档

代付代付渠道列表参考

查看文档

集成步骤

代付下单

商户服务端调用 代付下单接口 发起付款请求，PayCools 受理后返回交易状态。付款可能立即成功，也可能进入异步处理状态。

请求地址：POST /open-api/disbursement/transfer

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
mchOrderId	是	string(10-32)	商户订单号，需唯一
idempotencyId	是	string(10-32)	幂等号，需唯一
countryCode	是	string	国家/地区代码：`PH` / `ID` / `MY` / `TH` / `AE`
currency	是	string	交易币种：`PHP` / `IDR` / `MYR` / `THB` / `AED`
amount	是	long	交易金额，单位：分
accountNo	是	string(1-50)	收款账号
accountName	是	string(1-128)	收款人姓名
payMethodCode	是	string	支付方式代码：`BANK` / `EWALLET` / `PROMPTPAY`
transferCode	条件必填	string	渠道代码（`payMethodCode` 为 `BANK` 或 `EWALLET` 时必填）
accountType	是	string	账户类型：`MOBILE_NUMBER` / `BANK_ACCOUNT` / `NATIONAL_ID` / `EWALLET_ID`
beneficiaryType	是	string	收款人类型：`INDIVIDUAL` / `ORGANIZATION`
accountTaxId	否	string	收款人税号（AE 银行转账时必填）
relationship	否	string	收款人与商户的关系
mobile	否	string	收款人手机号
remark	否	string	备注信息
beneficiaryAddress	条件必填	string	收款人地址（AE 银行转账时必填）

💡

amount 单位为分，10000 代表 100.00。sign 字段为请求签名，签名规则请参考配置与签名。商户提交的 mchOrderId 和 idempotencyId 均需保证唯一性。

请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/disbursement/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "<your_sign>",
    "param": "{\"timestamp\":1715595802,\"mchOrderId\":\"DS20240513001\",\"idempotencyId\":\"ID20240513001\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"amount\":10000,\"accountNo\":\"09123456789\",\"accountName\":\"Juan Dela Cruz\",\"payMethodCode\":\"EWALLET\",\"transferCode\":\"GCASH\",\"accountType\":\"MOBILE_NUMBER\",\"beneficiaryType\":\"INDIVIDUAL\",\"mobile\":\"09123456789\",\"remark\":\"test transfer\"}"
}'

响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "DS20240513001",
    "transactionId": "T1789964654026559488",
    "transactionStatus": "PENDING",
    "transactionTime": "2024-05-13 15:26:00"
  }
}

⚠️

申请付款后，可能会因为字段格式不符合要求、支付方式合约未开通、填写金额超出支持范围等原因，直接收到失败响应。通过 API 发起的付款不可撤销，一旦发起就不能撤回。

📖

完整的请求参数说明与响应结构，请查看代付下单接口文档。

接收代付结果通知

代付交易状态变更时，PayCools 会通过异步回调将结果通知到商户配置的 notifyUrl 地址。商户收到通知后需验证签名，并根据交易结果更新订单状态。

回调方向：PayCools -> 商户

通知请求体结构：

参数名	类型	说明
appId	string	商户 AppID
sign	string	对 `param` 的 RSA 签名值
param	string	业务参数 JSON 字符串

param 参数说明：

参数名	类型	说明
eventName	string	事件类型：`disbursement.success` / `disbursement.failed`
mchOrderId	string	商户订单号
transactionId	string	交易流水号
countryCode	string	国家/地区代码
currency	string	交易币种
amount	long	交易金额，单位：分
transactionStatus	string	交易状态：`PENDING` / `COMPLETED` / `FAILED`
createTime	string	交易创建时间
returnTime	string	交易完成时间
remark	string	备注信息
failedCode	string	失败错误码（失败时返回）
failedMessage	string	失败错误描述（失败时返回）

通知示例

{
  "appId": "733b887a4a784708bb369524db5b6ded",
  "sign": "<platform_sign>",
  "param": "{\"eventName\":\"disbursement.success\",\"mchOrderId\":\"DS20240513001\",\"transactionId\":\"T1789964654026559488\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"amount\":10000,\"transactionStatus\":\"COMPLETED\",\"createTime\":\"2024-05-13 15:26:00\",\"returnTime\":\"2024-05-13 15:28:00\",\"remark\":\"test transfer\"}"
}

商户响应示例

{
  "code": 10000,
  "message": "Success"
}

商户处理步骤：

使用平台公钥对 sign 进行验签，确保通知来源可信
解析 param JSON 字符串，获取 transactionStatus 交易结果
根据 mchOrderId 更新商户订单状态
返回 HTTP 200 及 JSON 响应体，通知 PayCools 已成功接收。响应格式：{"code": 10000, "message": "Success"}

📖

签名验证方式请参考配置与签名中的 RSA 签名验证 部分。完整的通知参数说明，请查看代付结果回调通知文档。

查询代付状态

商户可通过 查询代付状态接口 主动查询付款交易的状态，建议在未收到异步回调或需要对账时使用。

请求地址：POST /open-api/disbursement/check

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
mchOrderId	条件必填	string	商户订单号（与 `transactionId` 二选一）
transactionId	条件必填	string	交易流水号（与 `mchOrderId` 二选一）
countryCode	是	string	国家/地区代码

请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/disbursement/check' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "<your_sign>",
    "param": "{\"timestamp\":1715595900,\"mchOrderId\":\"DS20240513001\",\"countryCode\":\"PH\"}"
}'

响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "DS20240513001",
    "transactionId": "T1789964654026559488",
    "amount": 10000,
    "transactionStatus": "COMPLETED",
    "createTime": "2024-05-13 15:26:00",
    "returnTime": "2024-05-13 15:28:00",
    "failedCode": null,
    "failedMessage": null,
    "currency": "PHP",
    "remark": "test transfer",
    "countryCode": "PH"
  }
}

交易状态说明：

状态	说明
PENDING	交易处理中
COMPLETED	交易成功
FAILED	交易失败

📖

完整的请求参数说明与响应结构，请查看查询代付状态接口文档。

代付渠道参考

代付支持多种支付方式，不同国家/地区支持的渠道不同。商户可根据目标市场选择合适的 payMethodCode 和 transferCode 组合。

支付方式代码说明：

payMethodCode	说明	适用场景
BANK	银行转账	大额付款、企业付款
EWALLET	电子钱包	小额付款、个人收款
PROMPTPAY	PromptPay	泰国市场专属

支持国家/地区及渠道：

国家/地区	countryCode	币种	支持 payMethodCode
菲律宾	PH	PHP	BANK、EWALLET
印度尼西亚	ID	IDR	BANK、EWALLET
马来西亚	MY	MYR	BANK、EWALLET
泰国	TH	THB	BANK、PROMPTPAY
阿联酋	AE	AED	BANK

📖

各国家/地区支持的详细渠道列表及 transferCode 编码，请查看代付渠道列表文档。

API付款

集成准备

商务洽谈

技术参数配置

签名与验签

交互流程​

付款 — 成功下单

付款 — 下单失败

交易状态查询

接口列表​

集成步骤​

代付下单

接收代付结果通知

查询代付状态

代付渠道参考

交互流程

接口列表

集成步骤