开始集成

环境准备

在开始前，请您确保已完成 设置测试环境 步骤以便继续。

测试环境	https://p-gate-uat.checus.com/aggregate-pay/api/gateway/<PATH>
正式环境	https://pay-gate-hk-prod.checus.com/aggregate-pay/api/gateway/<PATH>

交互流程

关键接口

关联交互时序	调用方向	接口地址
调用Payment API下单	商户 -> Checus	/orderAndPay
异步通知商户结果	Checus -> 商户	/collectResultNotifyUrl
查询交易结果	商户 -> Checus	/orderQuery

集成步骤

1. 创建支付会话

调用 支付创建接口/oderAndPay API ，发起POST请求以创建支付。

在收银台模式下，您可选择：

• 不指定支付方式：展示全量可用支付方式；
• 指定支付方式：仅展示请求中指定的方式。

通用参数说明

无论您希望用户使用哪种支付方式，请求中都应包含以下基本字段：

• outTradeNo: 商户系统订单号（唯一）
• totalAmount: 金额
• currency: 币种
• country: 用户所在国家
• userId: 用户标识
• frontCallbackUrl: 支付完成后跳转地址
• notifyUrl: 支付结果通知回调（可在商户管理平台统一配置）
• integrate: 固定为 Hosted_Checkout
• expireTime: 关单时间，单位为秒。默认区间：1800~86400，不在区间内将被强制修正。

特定支付方式选择

目标	说明	图示	应如何配置
展示所有支付方式			不传 paymentDetail 字段
限定支付类型但不指定机构	例如限定网上银行，则收银台展示T-Pay、SberPay等		设置 paymentDetail.paymentMethodType，如 "NET_BANKING"
限定具体支付机构	例如只展示SberPay钱包		设置 paymentDetail.targetOrg，如 "SBERBANK"
限定卡类支付	例如仅展示所有卡类支付		设置 paymentDetail.paymentMethodType = "CARD"

2. 重定向至Checus收银台

调用 支付创建接口/oderAndPay API 成功后，将用户重定向至返回的 redirectUrl，完成支付。

3. 重定向至支付结果页

用户支付完成后，Checus会展示结果页。点击返回后，将跳转至商户在请求中设置的 frontCallbackUrl 页面，您需确保该 URL 在外部浏览器中可正常访问。

跳转逻辑对比（frontCallbackUrl形式说明）

跳转方式	跳转流程	是否推荐	优点	缺点
H5 页面内主动唤起 APP	页面加载后尝试主动识别并跳转 APP（需配合 URL Scheme / AppLink）	推荐	流程可控、灵活处理	实现复杂，需兼容多场景
AppLink / Universal Link（http/https）	系统自动尝试唤起 APP，失败时展示 Web 页降级处理	推荐	支持降级、体验较佳	需配合移动端配置支持
普通 H5（http/https）	停留在浏览器展示页面	不推荐	实现简单	无法唤起 APP，体验割裂
URL Scheme（scheme://）	系统尝试打开对应 APP，失败则停留空白页	不推荐	简单实现	无降级逻辑，失败时留白

Checus 追加参数

当跳转至 frontCallbackUrl 时，Checus会自动追加以下参数：

• outTradeNo: 商户订单号
• tradeToken: Checus订单号
• status: 当前订单状态 （仅供展示，请勿用于更新订单状态）

请勿依赖 status 参数更新商户订单状态，应使用 获取支付结果 中回调或查询结果为准，确保交易结果准确。

4. 获取支付结果

方式1 . 支付结果通知

支付完成后，Checus 会通过回调向您发起 支付结果通知/collectResultNotifyUrl API 。可能多次重试，直到您返回成功响应。

回调地址配置方式：

• 接口传入：通过 /orderAndPay 的 notifyUrl 参数传入，仅对当前订单生效；
• 平台设置：在 商户管理平台 配置全局回调地址，适用于所有订单。

您在收到支付结果通知后，应返回处理结果。如果未响应或返回失败，Checus 将按以下间隔重试通知： 0s / 30s / 300s / 600s / 3600s / 43200s，最多重试 6 次。

方式2 . 主动查询支付结果

若未收到通知，或订单状态不明确，可主动调用 交易查询/orderQuery API 获取支付结果。

您应根据响应中的 code 判断查询是否成功，并通过 data.status 判断支付状态。请勿依据 code、msg 或 data.resultMsg 判断支付状态。

如遇报错，请参考 错误码列表 排查。

支付结果状态列表

状态	说明
SUCCESS	支付成功
PENDING	等待支付中
FAILED	支付失败
CLOSED	超时未支付，交易关闭