收银台模式

全球收单

收银台支付集成

收银台集成模式下，用户下单后，跳转到 PayCools 构建的 H5 收银页面支付。PayCools H5 收银页面展示可选的支付方式列表，同时支持自适应设备屏幕大小、多语言等特性。该集成模式下，商户无需开发收银台页面，可极大简化商户集成，缩短上线周期。

关于收银台集成模式的更多信息，请查看集成模式概览。

集成准备

1.1

商务洽谈

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

1.2

技术参数配置

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

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

1.3

签名与验签

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

交互流程

接口列表

说明	调用方向	接口PATH	API文档
收银台下单接口	`商户` -> `PayCools`	/open-api/payment/checkout/generate	查看
收银台查询接口	`商户` -> `PayCools`	/open-api/payment/checkout/query	查看
获取收银台可用支付渠道接口	`商户` -> `PayCools`	/open-api/payment/checkout/channel	查看
收银台订单关闭接口	`商户` -> `PayCools`	/open-api/payment/checkout/close	查看
收银台支付结果通知	`PayCools` -> `商户`	`<在商户后台配置的路径>`	查看

环境信息

测试环境

https://globalapi-dev.paycools.com:8902<接口PATH>

生产环境

https://openapi.paycools.com<接口PATH>

创建支付（收银台下单）

商户服务端调用 收银台下单接口 创建支付交易，PayCools 返回包含收银台页面 URL 的响应。商户客户端通过重定向引导用户进入收银台完成支付。

请求地址：POST /open-api/payment/checkout/generate

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
mchOrderId	是	string	商户订单号，需唯一
merchantLogo	否	string	商户 Logo URL
language	否	string	收银台语言，如 `en`、`zh`
countryCode	是	string	国家/地区代码，如 `PH`
currency	是	string	交易币种，如 `PHP`
settlementCurrency	否	string	结算币种
channelTypeList	否	list	限定支付方式类型列表
channelCodeList	否	list	限定支付渠道编码列表
amount	是	long	交易金额，单位：分
customerName	否	string	顾客姓名
email	否	string	顾客邮箱
mobile	否	string	顾客手机号
expireSeconds	否	int	订单过期时间（秒），默认 3600
notifyUrl	是	string	支付结果异步回调地址
redirectUrl	否	string	支付完成后跳转地址
remark	否	string	备注信息

💡

amount 单位为分，10000 代表 100.00。sign 字段为请求签名，签名规则请参考配置与签名。

请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/checkout/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "A5Vd8NcQvU3QT41Yee2jCIK58jDAKZ6kP5gEE4q7Yu92hUCY3k00FKTSlCNU+CcZm0LSrGbEMFMID3p7uvXaqy5khNv3kPndrgp7MIRHUmQnMgRK+g1XG7PzWdnrqlXc3g+L+kqVja+qrFRz+uVS6GLKLR1P4AtgTa9dok6NU7YTWOnG9r/FwIVx/At4czfEpI10pvg2TptVpiANmseGmz4G30hkaYTTNahkcOMQJn6PDFjivHvjNLZNJVOqHQzVUa+kca1yZZMPHtgxR647KjoY2oAjjl0Y45GL6zP9qHD/eVwcPPAPrRZ4K2o05OJnPf67fAcWNVqpnu6ZGQIXhQ==",
    "param": "{\"timestamp\":1715595802,\"mchOrderId\":\"10e5595801938341100\",\"merchantLogo\":\"https://test.img\",\"currency\":\"PH\",\"settlementCurrency\":\"PHP\",\"countryCode\":\"PH\",\"customerName\":\"name\",\"email\":\"test@email.com\",\"mobile\":\"09123456789\",\"amount\":10000,\"expireSeconds\":3600,\"remark\":\"remark\",\"notifyUrl\":\"https://www.test.com\",\"redirectUrl\":\"https://www.test.com\"}"
}'

响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "checkoutId": "CH1789964654026559488",
    "checkoutUrl": "https://cashier.paycools.com/checkout/NzQxPl1wE-cdtloi1h0pTgc23ZcdGdXiGGZ2YvywJ-o=",
    "status": "PENDING",
    "expiresTime": "2024-05-14 15:27:00"
  }
}

商户获取到 checkoutUrl 后，将其返回给前端进行跳转，用户即可进入 PayCools 收银台完成支付。

📖

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

接收支付结果通知

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

回调方向：PayCools -> 商户

通知请求体结构：

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

param 参数说明：

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

通知示例

{
  "appId": "733b887a4a784708bb369524db5b6ded",
  "sign": "<platform_sign>",
  "param": "{\"eventName\":\"CHECKOUT_PAY\",\"checkoutId\":\"CH1789964654026559488\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"settlementCurrency\":\"PHP\",\"mchOrderId\":\"10e5595801938341100\",\"transactionId\":\"T1789964654026559489\",\"amount\":10000,\"transactionStatus\":\"COMPLETED\",\"createTime\":\"2024-05-13 15:26:00\",\"returnTime\":\"2024-05-13 15:28:00\",\"channelCode\":\"GCASH\",\"remark\":\"remark\"}"
}

商户处理步骤：

使用平台公钥对 sign 进行验签，确保通知来源可信
解析 param JSON 字符串，获取 transactionStatus 支付结果
根据 mchOrderId 更新商户订单状态
返回 HTTP 200 响应，通知 PayCools 已成功接收

📖

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

查询支付订单

商户可通过 收银台查询接口 主动查询订单的支付状态，建议在未收到异步回调或需要对账时使用。

请求地址：POST /open-api/payment/checkout/query

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
checkoutId	是	string	收银台订单号，由下单接口返回

请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/checkout/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "<your_sign>",
    "param": "{\"timestamp\":1715595900,\"checkoutId\":\"CH1789964654026559488\"}"
}'

响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "checkoutId": "CH1789964654026559488",
    "status": "PAID",
    "expiresTime": "2024-05-14 15:27:00",
    "transactionList": [
      {
        "transactionId": "T1789964654026559489",
        "transactionStatus": "COMPLETED",
        "channelCode": "GCASH",
        "transactionCreateTime": "2024-05-13 15:26:00",
        "transactionReturnTime": "2024-05-13 15:28:00"
      }
    ]
  }
}

状态说明：

状态	说明
PENDING	待支付
PAID	已支付
CLOSED	已关闭

交易状态说明：

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

📖

完整的请求参数说明与响应结构，请查看收银台查询接口文档。

获取可用支付渠道

商户可通过 获取收银台可用支付渠道接口 查询指定国家/地区支持的支付渠道列表，用于提前展示可用的支付方式。

请求地址：POST /open-api/payment/checkout/channel

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
countryCode	是	string	国家/地区代码，如 `PH`

请求示例

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

响应示例

{
  "code": 10000,
  "message": "Success",
  "data": {
    "list": [
      {
        "channelType": "WALLET",
        "channelCode": "GCASH",
        "countryCode": "PH",
        "currency": "PHP"
      },
      {
        "channelType": "BANK",
        "channelCode": "BPI",
        "countryCode": "PH",
        "currency": "PHP"
      }
    ]
  }
}

📖

完整的请求参数说明与响应结构，请查看获取收银台可用支付渠道接口文档。

关闭收银台订单

当用户取消支付或订单超时等情况，商户可调用 收银台订单关闭接口 关闭该收银台订单，关闭后该订单将无法再进行支付。

请求地址：POST /open-api/payment/checkout/close

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（秒）
checkoutId	是	string	收银台订单号，由下单接口返回

请求示例

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/checkout/close' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "<your_sign>",
    "param": "{\"timestamp\":1715595900,\"checkoutId\":\"CH1789964654026559488\"}"
}'

响应示例

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

📖

完整的请求参数说明与响应结构，请查看收银台订单关闭接口文档。