开始集成

环境准备

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

环境信息如下：

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

交互流程

关键接口

交互名称	调用方向	接口地址
发起退款	商户 → Checus	/refund
退款结果通知	Checus → 商户	/refundResultNotifyUrl
查询退款交易	商户 → Checus	/refundQuery

集成步骤

1. 创建退款会话

调用 退款申请/refund API ，发起POST请求以创建退款。

2. 退款状态及结果查询

退款发起后，Checus 会向银行或相关机构提交原路退款请求，并通过 退款通知/refundResultNotifyUrl API 通知商户退款状态。

状态	描述	说明
REFUND_SUCCESS	退款成功	渠道已成功受理退款申请，实际到账时间受渠道限制，通常21日内到账。
REFUND_PENDING	退款处理中	退款请求已发起，渠道受理中。
REFUND_FAILED	退款失败	退款因某种原因未能完成。

方式1 . 退款结果通知

退款成功后，Checus 会异步回调商户配置的回调地址，发起 退款通知/refundResultNotifyUrl API。回调可能多次发送，直到商户返回成功响应。

回调地址配置方式：

• 接口参数设置：退款申请时，传入 refundNotifyUrl，该配置仅对本次退款生效，覆盖全局配置。
• 商户平台设置：通过 商户管理平台 统一配置退款回调地址，适用于所有退款。 您在收到支付结果通知后，应返回处理结果。如果未响应或返回失败，Checus 将按以下间隔重试通知： 0s / 30s / 300s / 600s / 3600s / 43200s，最多重试 6 次。

方式2 . 主动查询退款结果

若未收到通知，或订单状态不明确，可调用 退款查询/refundQuery API 主动查询退款状态。

可通过 code 判断接口调用是否成功，通过 data.status 判断退款状态。

避免使用 msg 或 resultMsg 判断退款结果。

方式3 . 通过商户管理平台查询退款

无论通过API或平台发起退款，商户均可登录 商户管理平台，'收款管理' ＞ '退款查询'，查看退款状态和进度。