纯API支付集成

纯API集成模式下，商户需要自行构建相关的支付页面，如：收银页、支付结果页等，因此，该模式需要商户投入更多的研发成本。

关于纯API集成模式的更多信息，请查看集成模式概览。

1. 集成准备

1.1 商务洽谈

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

1.2 技术参数配置

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

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

1.3 签名与验签

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

交互流程

3. 接口列表

收款收款下单接口商户 → PayCools

POST /open-api/payment/generate

查看 API 文档

收款收款状态查询接口商户 → PayCools

POST /open-api/payment/query

查看 API 文档

订单订单关闭接口商户 → PayCools

POST /open-api/payment/close

查看 API 文档

通知收款结果通知PayCools → 商户

回调路径：<在商户后台配置的路径>

查看 API 文档

交易交易撤销接口商户 → PayCools

POST /open-api/payment/void

查看 API 文档

4. 环境信息

测试环境

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

生产环境

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

5. 集成步骤

5.1 创建支付（纯API下单）

商户服务端调用 收款下单接口 创建支付交易。PayCools 返回支付数据（如跳转 URL、二维码内容、虚拟账户信息等），商户自行决定如何展示给用户完成支付。

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

请求体结构：

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

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳（毫秒）
mchOrderId	是	string	商户订单号，格式：字母+数字，1-32位
amount	是	long	收款金额（单位为分，印尼国家使用元）
countryCode	是	string	国家编码（`PH`/`ID`/`MY`/`TH`/`RU`）
currency	是	string	货币代码（`PHP`/`IDR`/`MYR`/`THB`/`RUB`）
channelType	是	string	支付渠道类型（`QR`/`ONLINE_BANKING`/`EWALLET`/`BANK_TRANSFER`/`CARD`/`DIRECT_DEBIT`/`PAYLATER`）
channelCode	是	string	平台收单渠道代码
payToken	否	string	代扣 token（`channelType` 为 `DIRECT_DEBIT` 时必填）
customerName	条件	string	付款人姓名（部分渠道类型时必填）
email	条件	string	付款人邮箱（部分渠道类型时必填）
mobile	条件	string	付款人电话（部分渠道类型时必填）
terminalType	条件	string	设备类型（`WEB`/`WAP`）（部分渠道类型时必填）
osType	否	string	操作系统类型（`IOS`/`ANDROID`）
notifyUrl	是	string	商户交易通知 URL
redirectUrl	条件	string	重定向 URL（部分渠道类型时必填）
remark	否	string	收单备注
expiredSeconds	否	int	订单过期时间（秒），最短 60s，最长 86400s
wechatpay	否	object	微信支付相关参数
goodsDetails	条件	list	商品信息（`PAYLATER` 时必填）
billingAddress	条件	object	账单地址（`PAYLATER` 时必填）
shippingAddress	条件	object	收件地址（`PAYLATER` 时必填）

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

请求示例：

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/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\",\"currency\":\"PHP\",\"countryCode\":\"PH\",\"channelType\":\"QR\",\"channelCode\":\"PH_QRPH_DYNAMIC\",\"customerName\":\"name\",\"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": "10e051066810618100",
    "transactionId": "CU510579106014826496",
    "transactionStatus": "PENDING",
    "payData": "00020101021128760011ph.ppmi.p2m...",
    "channelType": "QR",
    "channelCode": "PH_QRPH_DYNAMIC"
  }
}

响应参数说明：

参数名	类型	说明
mchOrderId	string	商户订单号
transactionId	string	平台交易流水号
transactionStatus	string	交易状态
payData	string	实际支付数据（VA、跳转 URL 或 QR Content）
channelType	string	支付渠道类型
channelCode	string	平台收单渠道代码
cashierUrl	string	还款指引链接
expiresTime	string	支付过期时间

商户获取到 payData 后，根据 channelType 决定展示方式：二维码扫码支付（QR）、跳转到支付页面（EWALLET/ONLINE_BANKING）或展示虚拟账户信息（BANK_TRANSFER）。

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

5.2 接收支付结果通知

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

回调方向：PayCools → 商户

通知请求体结构：

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

param 参数说明：

参数名	类型	说明
eventName	string	事件名称（`order.payment.success`/`order.payment.failed`/`order.void.success`）
mchOrderId	string	商户订单号
transactionId	string	交易流水号
countryCode	string	国家编码
currency	string	交易币种
amount	long	交易金额（单位为分，印尼国家使用元）
transactionStatus	string	交易状态（`PENDING`/`COMPLETED`/`FAILED`）
createTime	string	交易创建时间
returnTime	string	交易完成时间
channelCode	string	支付渠道编码
remark	string	备注信息
failedCode	long	失败错误码（失败时返回）
failedMessage	string	失败错误描述（失败时返回）
qrphInvoiceNo	string	QRPh 付款记录编号（QRPh 渠道时返回）

通知示例：

{
  "sign": "V6HQvEZaLF5MSH8TcOVdqPj7fLyvdrAOPm74rW9svpclBIVPlokyiZqPXl09/yAOS8PNnganUtvRvie9MAxJwtYOkDMXxxi4gWjPl3D9L6W4fnVeC28HjhZhWrSgwlecJG6SuHM3odTHAxr5WQUuOxsYFtx+c74Ew+ZzuICCH3dA4+uzNEbDyB8QmBF94nM1LFhDId/VEMxdbj8xKJuOMiSBgwAWaFElm5YCfgmrZpU/qLnuGX2hNxQAMKY2GAw+4VpphYpHG8Xak5+PlqFWKp8mKJ9DgyphVf0ACGpcjOQp0S1V+S1HMMVU0AkW6c8n0weOMu3l6k6cPHsjEe/jSQ==",
  "param": "{\"eventName\":\"order.payment.success\",\"countryCode\":\"PH\",\"currency\":\"PHP\",\"amount\":50000,\"channelCode\":\"PH_GCASH_URL\",\"mchOrderId\":\"Platform653350151938813\",\"createTime\":\"2024-07-09T15:37:52+08:00\",\"remark\":\"test payment\",\"returnTime\":\"2024-07-09T16:20:23+08:00\",\"transactionId\":\"CU4Y9920490660433920\",\"transactionStatus\":\"COMPLETED\"}"
}

商户处理步骤：

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

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

5.3 查询支付订单

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

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

请求体结构：

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

param 参数说明：

参数名	是否必填	类型	说明
mchOrderId	否	string	商户订单号（与 `transactionId` 传其中之一）
transactionId	否	string	交易编号（与 `mchOrderId` 传其中之一）
countryCode	是	string	国家编码（`PH`/`ID`/`MY`/`TH`/`RU`）
timestamp	是	long	当前时间戳（毫秒）

请求示例：

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

响应示例：

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "10e051066810618100",
    "transactionId": "CU510579106014826496",
    "countryCode": "PH",
    "channelCode": "PH_QRPH_DYNAMIC",
    "amount": 10000,
    "currency": "PHP",
    "payData": "00020101021128760011ph.ppmi.p2m...",
    "transactionStatus": "PENDING",
    "createTime": "2024-07-09T15:37:52+08:00"
  }
}

交易状态说明：

状态	说明
PENDING	交易处理中
COMPLETED	交易成功
FAILED	交易失败
VOIDED	已撤销
VOIDING	撤销中

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

5.4 关闭订单

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

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

param 参数说明：

参数名	是否必填	类型	说明
mchOrderId	否	string	商户订单号（与 `transactionId` 传其中之一）
transactionId	否	string	交易编号（与 `mchOrderId` 传其中之一）
countryCode	是	string	国家编码（`PH`/`ID`/`MY`/`TH`/`RU`）
timestamp	是	long	当前时间戳（毫秒）

请求示例：

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/close' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "A5Vd8NcQvU3QT41Yee2jCIK58jDAKZ6kP5gEE4q7Yu92hUCY3k00FKTSlCNU+CcZm0LSrGbEMFMID3p7uvXaqy5khNv3kPndrgp7MIRHUmQnMgRK+g1XG7PzWdnrqlXc3g+L+kqVja+qrFRz+uVS6GLKLR1P4AtgTa9dok6NU7YTWOnG9r/FwIVx/At4czfEpI10pvg2TptVpiANmseGmz4G30hkaYTTNahkcOMQJn6PDFjivHvjNLZNJVOqHQzVUa+kca1yZZMPHtgxR647KjoY2oAjjl0Y45GL6zP9qHD/eVwcPPAPrRZ4K2o05OJnPf67fAcWNVqpnu6ZGQIXhQ==",
    "param": "{\"mchOrderId\":\"10e051066810618100\",\"countryCode\":\"PH\",\"timestamp\":\"1677133173758\"}"
}'

响应示例：

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "10e051066810618100",
    "transactionId": "CU510579106014826496",
    "channelCode": "PH_QRPH_DYNAMIC",
    "status": "CLOSED",
    "closedTime": "2024-07-09T15:37:52+08:00"
  }
}

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

5.5 交易撤销

商户可调用 交易撤销接口 撤销一笔已成功的交易。目前仅支持 Thailand Dynamic QR（TH_THAILAND_DYNAMIC_QR）的交易撤销。

请求地址：POST /open-api/payment/void

param 参数说明：

参数名	是否必填	类型	说明
timestamp	是	long	当前时间戳
countryCode	是	string	国家编码（`TH`）
originalTransactionId	是	string	原交易 ID
mchVoidOrderId	是	string	撤销请求流水号

请求示例：

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/payment/void' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "733b887a4a784708bb369524db5b6ded",
    "sign": "A5Vd8NcQvU3QT41Yee2jCIK58jDAKZ6kP5gEE4q7Yu92hUCY3k00FKTSlCNU+CcZm0LSrGbEMFMID3p7uvXaqy5khNv3kPndrgp7MIRHUmQnMgRK+g1XG7PzWdnrqlXc3g+L+kqVja+qrFRz+uVS6GLKLR1P4AtgTa9dok6NU7YTWOnG9r/FwIVx/At4czfEpI10pvg2TptVpiANmseGmz4G30hkaYTTNahkcOMQJn6PDFjivHvjNLZNJVOqHQzVUa+kca1yZZMPHtgxR647KjoY2oAjjl0Y45GL6zP9qHD/eVwcPPAPrRZ4K2o05OJnPf67fAcWNVqpnu6ZGQIXhQ==",
    "param": "{\"originalTransactionId\":\"1693814345718435840\",\"mchVoidOrderId\":\"8800014892342565436\",\"countryCode\":\"TH\",\"timestamp\":\"1677133173758\"}"
}'

响应示例：

{
  "code": 10000,
  "message": "Success",
  "data": {
    "state": "SUCCESS",
    "voidTransactionId": "CU510579106014826500"
  }
}

撤销状态说明：

状态	说明
SUCCESS	撤销成功
FAILED	撤销失败
PENDING	撤销处理中

📄完整的请求参数说明与响应结构，请查看交易撤销接口文档。

1. 集成准备​

1.1 商务洽谈​

1.2 技术参数配置​

1.3 签名与验签​

交互流程

3. 接口列表​

4. 环境信息​

5. 集成步骤​

5.1 创建支付（纯API下单）

5.2 接收支付结果通知

5.3 查询支付订单

5.4 关闭订单

5.5 交易撤销

1. 集成准备

1.1 商务洽谈

1.2 技术参数配置

1.3 签名与验签

3. 接口列表

4. 环境信息

5. 集成步骤