收银台模式

本地收单

收银台模式

收银台模式下，用户下单后进入 PayCools 收银台，在收银台中选择支付方式并完成支付。收银台会展示当前订单可用的支付方式，您无需自行开发支付方式选择页面，可减少接入工作。

模式简介

在收银台模式中，PayCools 负责渲染支付页面，用户在 PayCools 的收银台上自行选择支付方式（如 QR 或 EWALLET）。商户只需获取收银台链接并跳转即可，无需自行开发支付页面。

接口可限定多种支付方式：商户在下单接口中可以指定支持哪些支付方式，例如「QR + EWALLET」或仅「QR」。
用户自行选择：用户打开收银台后，会在页面上看到可选的支付方式，自行选择其一完成支付。
收银台由 PayCools 提供：这是一个由 PayCools 维护的响应式 H5 页面，支持多语言与自适应设备。

适用场景

需要快速上线：不想投入大量时间开发支付页面，直接使用 PayCools 成熟的收银台。
支付方式多样：希望让用户自行选择支付方式，而不是由商户在接口中锁定某一种支付方式。
PC / H5 页面：用户从 PC 浏览器或手机浏览器打开，收银台会自适应设备尺寸。

交互流程

收银台的特性

响应式设计：自动适配 PC、手机、平板等不同屏幕。
多语言：根据用户浏览器语言或接口指定语言展示对应语言版本。
支付方式列表：根据接口指定的支付方式类型，动态展示对应的支付选项。
样式可定制：支持自定义收银台的 Logo。

接入步骤

1. 创建收银台

在您的服务端创建收银台并提交订单信息。以下为创建收银台的请求和响应示例。查看文档接口

创建收银台请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/checkout/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "your appId",
    "sign": "********************************",
    "param": "{\"timestamp\":1790662526,\"mchOrderId\":\"NSDdgrVwhA4DTYEyMNtHWIH14hh\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"settlementCurrency\":\"PHP\",\"channelTypeList\":null,\"channelCodeList\":null,\"amount\":5000,\"customerName\":\"test\",\"email\":\"test@example.com\",\"mobile\":\"09234567890\",\"notifyUrl\":\"https://test.com\",\"redirectUrl\":\"https://test.com\"}"
}'

创建收银台响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "checkoutId": "CH2104817245258649600",
    "checkoutUrl": "https://globalapi-dev.paycools.com:8904/cashier/checkout/SZGYAPSYaC9e9R0lDHtX9OOiFGSgMSjwjVPuV5DLEEY=",
    "status": "PENDING",
    "expiresTime": "2026-09-29 14:45:11"
  }
}

2. 打开收银台

创建成功后，将用户引导至 PayCools 收银台。用户在收银台中选择支付方式，并按照页面提示完成支付。

3. 确认支付结果

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

接收支付结果通知：PayCools 会将支付结果发送至您设置的通知地址。收到通知后，请按照对应通知文档完成验签，并更新订单状态。
主动查询支付结果：如果未收到通知或需要再次确认支付状态，您可以查询对应的支付记录。

请以支付结果通知或主动查询获得的状态为准。用户返回您的页面不代表支付已经成功。

接口说明

在收银台模式下，商户需要调用 PayCools 的收银台接口来获取收银台链接。下单接口的关键参数包括：

参数	说明
mchOrderId	商户订单号（唯一）
countryCode	交易国家，例如：PH
currency	币种，本地收单，须和交易国家一一对应，例如：PHP
settlementCurrency	结算币种，本地收单，须和交易国家一一对应，例如：PHP
channelTypeList	渠道类型，可指定多种，限制收银台可用的渠道类型，例如「QR + EWALLET」
channelCodeList	限制使用的具体渠道，如传入，channelTypeList 必填
amount	订单金额
customerName	付款人姓名
email	付款人邮箱
mobile	付款人手机号
notifyUrl	支付结果异步通知地址
redirectUrl	支付完成后用户跳转回商户的地址
expireSeconds	收银台有效期（秒），最长 86400（1 天），超时后收银台状态变为 CLOSED

备注

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

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

返回内容：接口会返回一个 cashierUrl，商户需要把这个链接给到用户。

收银台订单状态与集成建议

收银台订单状态

收银台查询接口的返回参数 status 取值如下：

状态	含义	说明
`PENDING`	待支付	用户尚未完成支付，可继续选择任一可用支付方式付款
`PAID`	支付成功	收银台自动跳转支付成功页，订单完结
`CLOSED`	已关闭	收银台过期或商户主动关闭；不可再通过该收银台创建新的支付交易，关闭前已生成的交易仍可能可以支付

以收银台订单状态为准

收银台模式下，用户在收银台内产生的多次支付结果最终都会汇总到收银台订单（checkoutId）上。建议商户以收银台订单的状态为准，而不是以单个支付方式的中间结果作为订单最终状态。

原因在于，收银台允许用户在同一订单内多次选择不同支付方式完成付款，其中部分渠道本身不存在「失败」状态；某次支付失败在本质上等同于「尚未支付」，不应影响用户改用其他支付方式继续付款。因此，当单一支付方式支付失败时，PayCools 不会关闭收银台订单，订单状态仍为 PENDING。

支付结果回调

收银台模式只对成功的交易发送支付结果回调；某一种支付方式支付失败时，PayCools 不会发送回调。

原因在于，用户在某一次支付方式失败后仍可继续选择其他支付方式完成付款，因此不会因单个支付方式失败而通知商户「该订单支付失败」。商户若担心漏单，可在收银台订单状态变为 PAID 后，或通过支付查询接口主动确认交易结果。

回调的投递与重试遵循统一规则（以 HTTP 200 判定回调成功、失败后的重试频率与时限等），详见支付通用规则 · 回调通知规则。

CLOSED 的触发场景

CLOSED 表示收银台订单已关闭：无法再通过该收银台创建新的支付交易；关闭前已生成、仍在有效期内的交易仍可能可以支付。通常在以下两种场景下出现：

收银台过期：创建收银台时通过 expireSeconds 参数控制有效期（最长 86400 秒，即 1 天），超过有效期后收银台状态变为 CLOSED。
商户主动关闭：您可调用收银台关闭接口主动关闭订单，关闭后状态变为 CLOSED。

支付成功后的行为

用户支付成功后，收银台状态变为 PAID，收银台会跳转到支付成功页；此时该收银台订单已完结，用户无法再通过该收银台创建新的支付交易。

仅在一种极少见的情况下会出现「同一收银台订单对应多笔已支付交易」：用户在支付前曾于收银台多次选择支付方式、生成了多笔交易，并在后续操作中对其中多笔均完成了支付。遇到此类情况，商户只需以收银台订单状态为准进行核对；如终端用户对此提出反馈，按客诉流程处理即可。

备注

商户侧应以收银台订单状态（PENDING / PAID / CLOSED）及支付结果通知为准更新订单：收银台只对成功的交易发送回调，单渠道失败不会回调，也请勿因单个支付方式的失败而关闭整笔订单。创建收银台示例请见上文「接入步骤」。

集成准备

在使用收银台模式前，请确保：

已在商户后台完成公钥配置，获取 AppID 与 平台公钥
理解签名与验签机制，接口调用需在请求参数中携带 sign
查看环境信息，确认请求地址
准备好接收支付结果异步通知的接口（Notify URL）