API直连

本地收单

API 直连

API 直连模式下，用户在您的网站或应用中选择支付方式，您的服务端调用该支付方式对应的接口创建支付。接口返回统一的支付数据 payData，按渠道不同返回二维码内容、跳转链接或虚拟账号，商户据此自行渲染或展示。

模式简介

在纯 API 模式中，商户负责渲染支付页面。与收银台模式相比，核心区别在于：

接口限定固定一种支付方式：下单接口中，商户需指定唯一的渠道类型与渠道码（如 QR + PH_QRPH_DYNAMIC）。
返回具体的支付数据：PayCools 返回统一的 payData——QR 渠道返回二维码内容，电子钱包返回跳转链接，VA / 账单返回虚拟账号或付款参考号；商户据此自行渲染或跳转。
商户自行实现收银台：商户需要自行开发收银页面、支付结果页，并处理用户交互。

适用场景

需要完全自定义体验：希望对收银页样式、交互流程有完全掌控，不使用 PayCools 通用收银台。
已有成熟的收银系统：商户已经有一套成熟的收银页面，只需对接 PayCools 获取支付信息。
需要统一多渠道支付：同时对接多个支付渠道，希望在自有收银页统一展示，而不是跳转到不同的第三方页面。

交互流程

API 直连模式不展示 PayCools 的支付方式选择页。用户后续看到的支付页面或支付指引由所选支付方式及返回的 payData 类型决定。

接入步骤

1. 创建支付

用户选择支付方式后，在您的服务端调用收款接口创建支付。以下为收款接口的请求和响应示例。查看文档接口

创建支付请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "your appId",
    "sign": "********************************",
    "param": "{\"timestamp\":1790668386,\"mchOrderId\":\"xAlQ4NHqV183OAICTkp\",\"currency\":\"PHP\",\"countryCode\":\"PH\",\"channelType\":\"QR\",\"channelCode\":\"PH_QRPH_DYNAMIC\",\"customerName\":\"PayCools\",\"email\":\"test@email.com\",\"mobile\":\"09123456789\",\"amount\":10000,\"remark\":\"remark\",\"notifyUrl\":\"https://www.test.com\",\"redirectUrl\":\"https://www.test.com\",\"terminalType\":\"WEB\"}"
}'

创建支付响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "huB7yF1l340",
    "transactionId": "CU5U4841812291227648",
    "transactionStatus": "PENDING",
    "payData": "00020101021128760011ph.ppmi.p2m0111OPDVPHM1XXX03157771480000000170416529481372394713405030005204601653036085802PH5908PayCools6015City Of Mandalu62310010ph.allbank05062110000803***88310012ph.ppmi.qrph0111OPDVPHM1XXXO6127DN0",
    "cashierUrl": "https://globalapi-dev.paycools.com:8904/webpay/cashier/9kbU8AGr0yWjMWTHxV-NbQ==",
    "channelType": "QR",
    "channelCode": "PH_QRPH_DYNAMIC"
  }
}

2. 引导用户完成支付

支付创建成功后，根据返回的 payData 类型引导用户：QR 内容渲染成二维码供用户扫码；跳转 URL 用于按钮跳转或直接跳转；VA / 参考号则展示给用户完成转账或缴费。

3. 确认支付结果

用户完成支付后，您可以通过以下方式确认支付状态：

接收支付结果通知：API 直连对交易成功与失败均会发送支付结果回调。收到通知后，请按照对应通知文档完成验签，并更新订单状态。回调的投递与重试规则（以 HTTP 200 判定成功、重试频率与时限等）见支付通用规则 · 回调通知规则。
主动查询支付结果：如果未收到通知或需要再次确认支付状态，您可以查询对应的支付记录。

请以支付结果通知或主动查询获得的状态为准。用户返回您的页面不代表支付已经成功。您可以在后台或通过查询接口核对订单的最终状态。

接口说明

纯 API 模式调用收款接口创建支付，下单关键参数说明如下：

参数	说明
mchOrderId	商户订单号（唯一）
countryCode	交易国家/地区，如 PH
currency	币种，须与交易国家对应，如 PHP
channelType	渠道类型，如 QR / EWALLET / VA 等
channelCode	渠道码，须与 channelType 对应，如 PH_QRPH_DYNAMIC
customerName	付款人姓名
email	付款人邮箱
mobile	付款人手机号
amount	订单金额
notifyUrl	支付结果异步通知地址
redirectUrl	支付完成后用户返回商户的地址

备注

付款人姓名，邮箱，手机号等个人信息参数，PayCools 目前不校验真实性（不会验证号码是否真实存在或已注册），但会校验格式；请按对应国家/地区的正确格式传入，各国家/地区手机号格式请参考支付通用规则。

完整的 API 参数说明、签名规则、请求 / 响应示例，请参考 API 文档。

返回内容

下单接口返回交易号与本次支付所需的支付数据，关键字段如下：

字段	说明
transactionId	PayCools 交易号
transactionStatus	交易状态，如 PENDING（待支付）
payData	渠道支付数据，按所选渠道返回二维码内容 / 跳转链接 / 虚拟账号
cashierUrl	还款 / 支付指引页
channelType / channelCode	本次实际使用的渠道类型与渠道码

关于 payData（推荐使用）：payData 会根据产品 / 渠道返回不同类型的内容：

QR 渠道：返回二维码内容（QR Content），商户需将其渲染成二维码图片；
VA / 账单渠道：返回虚拟账号（VA）或付款参考号，商户展示给用户完成转账 / 缴费；
WebPay / 电子钱包渠道：返回跳转 URL，商户可引导用户跳转或使用按钮打开。

关于 cashierUrl：cashierUrl 是 PayCools 提供的还款 / 支付指引页面，会根据渠道类型展示对应的支付指引：

QR 渠道：由 PayCools 将二维码渲染成标准支付页面，用户扫码即可支付；
跳转类渠道（WebPay / 电子钱包）：由 PayCools 做一层转发，最终仍会跳转到 payData 中的渠道地址，因此响应给客户的时间可能更长；
VA 渠道：展示用户如何使用虚拟账号完成还款的步骤。

集成建议：优先使用 payData 中的内容，交互更直接——QR 内容自行渲染、跳转链接直达渠道、VA / 参考号展示给用户；cashierUrl 适用于希望由 PayCools 渲染标准支付页 / 指引页的场景（QR 渲染、跳转转发或 VA 还款指引）。

商户需自行处理的环节

由于收银页面由商户自行实现，以下环节需要商户自行处理：

处理 payData：根据返回类型处理——QR 内容渲染成二维码、跳转 URL 用于跳转、VA / 参考号展示给用户。
支付结果轮询：在用户扫码 / 跳转后，商户需要轮询调用查询接口确认支付状态。
支付结果页：支付完成后，用户可能跳转回商户侧，商户需要展示对应的成功 / 失败页面。
异常处理：二维码过期、支付失败、超时未付等场景的处理。

集成准备

在使用纯 API 模式前，请确保：

已在商户后台完成公钥配置，获取 AppID 与 平台公钥
理解签名与验签机制，接口调用需在请求参数中携带 sign
查看环境信息，确认请求地址
准备好接收支付结果异步通知的接口（Notify URL）
开发收银页面，具备按 payData 类型渲染二维码 / 跳转 / 展示账号、轮询支付状态、展示支付结果的能力