API 付款

本地付款

API 付款

API 付款面向已具备业务系统的商户：由业务系统根据订单、结算或运营流程自动发起付款，无需人工在商户后台操作。PayCools 负责付款受理、渠道处理与结果回传，帮助商户将付款能力嵌入自有业务流程。

模式简介

在 API 付款模式中，付款由业务系统自动发起，适合将付款能力嵌入现有业务流程。与商户平台付款相比，主要区别如下：

系统自动发起：业务系统根据订单 / 结算流程调用接口创建付款，适合高频、大批量场景。
按业务规则选择渠道：发起付款时可指定收款渠道，支持各国本地银行与电子钱包。
结果异步返回：PayCools 受理后进入处理流程，最终结果通过异步通知或查询获取，受理结果不作为付款成功依据。
支持批量下单：除单笔下单外，还提供批量代付下单接口，一次提交一个批次。

适用场景

高频、大批量付款：用户提现、佣金发放、活动派奖等笔数多、需逐笔自动打款的场景。
与业务系统联动：由订单、结算或账务系统根据业务状态自动触发付款，无需人工介入。
批量结算：供应商结算、批量发薪等一次向多个收款人付款的场景，可使用批量代付下单。
需要自动对账：通过异步回调与查询接口把付款结果回写业务系统，自行对账。

交互流程

业务系统创建付款后，PayCools 负责推送渠道并回传结果；发起、接收通知、更新订单状态均由商户系统完成。

接入步骤

1. 创建付款（代付下单）

由业务系统调用代付下单接口发起付款。PayCools 受理后返回 PENDING，随后异步推送至渠道处理——下单接口不会直接返回成功，最终结果以异步通知或查询结果为准。查看文档接口

备注

建议在下单前先调用验卡接口校验收款账户：确认账户有效（accountStatus=VALID）且姓名匹配（accountNameMatchResult=MATCH）后再发起付款，可减少因账号或姓名错误导致的付款失败。验卡需单独开通。

接口：POST /open-api/disbursement/transfer

创建付款请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/disbursement/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "3490xxxxxxa8af",
    "sign": "<your_sign>",
    "param": "{\"countryCode\":\"PH\",\"currency\":\"PHP\",\"mchOrderId\":\"10e0604985585335100\",\"idempotencyId\":\"10e0604985585335100\",\"amount\":100,\"accountNo\":\"09206634895\",\"accountName\":\"test\",\"payMethodCode\":\"EWALLET\",\"transferCode\":\"GCASH\",\"beneficiaryType\":\"INDIVIDUAL\",\"accountType\":\"MOBILE_NUMBER\",\"timestamp\":1720604986}"
}'

创建付款响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "10e0604985585335100",
    "transactionId": "DU510974822121865216",
    "transactionStatus": "PENDING",
    "transactionTime": "2024-07-10T17:50:18+08:00"
  }
}

2. 接收代付结果通知

代付交易状态变更时，PayCools 会向您在商户后台配置的代付回调地址发送异步通知。回调地址在开发者设置 → 应用详情 → Webhook中配置。通知可能重复发送，直到商户返回成功响应；投递、重试与超时规则请参考通用回调通知规则。

商户需要做的事：

收到通知后，使用平台公钥对 sign 验签，确认通知来自 PayCools。
解析 param 中的交易结果，根据 eventName（disbursement.success / disbursement.failed）与 transactionStatus 更新本地订单状态。
若代付失败，读取 failedCode / failedMessage 定位失败原因。
返回 HTTP 200，告知 PayCools 已成功接收。

备注

完整的通知字段说明与通知示例，请参考代付结果回调通知文档。

3. 查询代付状态

未及时收到异步通知、回调通知接口异常，或需要对账、主动确认付款结果时，可调用查询接口获取一笔付款的最新状态。

商户需要做的事：

调用查询接口，传入 mchOrderId 或 transactionId（二者传其一）以及 countryCode。
根据返回的 transactionStatus 更新订单状态。
失败时从 failedCode / failedMessage 获取失败原因。

备注

完整的请求 / 响应参数，请参考查询代付状态接口文档。

接口说明

代付下单接口采用统一的 appId / sign / param 请求结构，其中 param 为业务参数的 JSON 字符串（签名针对 param 内容生成）。关键参数如下：

参数名	说明
`mchOrderId`	商户订单号，10–32 位，需唯一
`idempotencyId`	幂等键，同一笔请求保持不变，防止重复提交
`countryCode` / `currency`	付款国家与币种，二者必须匹配
`amount`	代付金额；单位以接口文档为准（印尼、越南为元，其余为分）
`accountNo` / `accountName`	收款账号与姓名。打款以账号为准，姓名仅记录透传，不校验
`payMethodCode` / `accountType` / `transferCode`	代付方式、账号类型与具体收款渠道编码

备注

代付打款只校验收款账号：只要账号正确即可完成打款，不会校验收款人姓名是否正确或真实。姓名填错通常不影响打款结果；如需事前确认户名，请使用验卡。

返回内容

下单接口返回交易编号与本次付款的即时状态，关键字段如下：

字段	说明
mchOrderId	商户订单号
transactionId	PayCools 唯一流水号，用于对账
transactionStatus	下单响应中固定为 `PENDING`；最终状态（`COMPLETED` / `FAILED`）通过异步通知或查询接口获取
transactionTime	交易创建时间

备注

下单响应中的 transactionStatus 固定为 PENDING，仅表示已受理，不能据此判定付款成功；最终结果以异步通知或查询结果为准。通过 API 发起的付款不可撤销，申请时请核对收款人信息与金额。

商户需自行处理的环节

PayCools 负责受理付款、推送渠道并回传结果，以下环节需要由您的业务系统完成：

创建付款：根据业务状态调用下单接口，逐笔传入收款人信息与付款金额，并保证 mchOrderId、idempotencyId 唯一。
（可选）付款前验卡：先校验账户有效性与姓名匹配，通过后再下单，可显著降低付款失败率。
接收并验签通知：回调到达后使用平台公钥验签，按 eventName 与 transactionStatus 更新订单。
状态确认：以异步通知或查询接口的最终状态为准，不要依据接口返回的 PENDING 或用户端展示判定成功。
失败处理与重试：按 failedCode / failedMessage 判断原因；余额不足等可恢复问题可重新发起。
对账：以 transactionId 为维度对账，并处理重复通知（幂等更新）。

集成准备

在接入 API 付款前，请确保：

已完成商务洽谈，并提供商户名称与邮箱，由技术支持发送账号信息。
已在商户后台完成公钥配置，获取 AppID 与平台公钥。
理解签名与验签机制，请求需携带 sign。
已在 API Key 页面配置代付结果回调地址（Notify URL）。
已查看环境信息，确认请求地址。
商户账户余额充足（付款金额 + 手续费）。