开始集成

环境准备

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

环境信息如下：


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

交互流程

关键接口

关联交互时序	调用方向	接口地址
发起付款请求	`商户` → `Checus`	/paymentOrderPay
付款结果通知	`Checus` → `商户`	/disbursementResultNotifyUrl
查询付款结果	`商户` → `Checus`	/paymentOrderQry

集成步骤

集成前说明

商户需下载付款申请模板，并在自身 App 或网站中采集用户付款要素。
按照《付款申请模板及填写规范》中的“填写规范”表格说明（标注为粉色背景的为必填项），构造接口参数进行请求。
请注意，付款请求**不可撤销**，一旦发起将无法撤回。

1. 创建支付会话

调用申请付款/paymentOrderPay API，发起POST请求以创建支付。

您提交的每笔订单需符合幂等校验，请求需携带唯一的 orderId。

如 Checus 检测到重复的 orderId，将返回 code=ORDER_REPEAT，并附带当前订单状态作为响应。

2. 获取支付结果

方式1 . 支付结果通知

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

回调通常发生在交易达到终态（如成功、失败、退票）后；但若支付中状态需商户/用户感知，也可能提前推送。

回调地址配置方式：

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

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

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

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

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

付款结果状态列表

2.1 主状态枚举

状态	描述	使用指引
SUCCESS	付款成功	-
PENDING	付款处理中	1. 付款申请提交后，订单将进入 PENDING 状态，直至达到终态（SUCCESS / FAILED / BOUNCEBACK）。 2. 在 PENDING 状态下可能存在多种情况，请参考子状态说明。
FAILED	付款失败	请参考错误码说明查找原因
BOUNCEBACK	出款退票	某些国家的金融系统在初始返回成功后，仍可能因以下原因退票： – 收款账户信息错误或被冻结 – 银行或清算网络异常该类订单状态将从 `SUCCESS` 变更为 `BOUNCEBACK`，资金将原路退回至商户账户。

2.2 子状态说明（适用于PENDING状态）

主状态	子状态	描述	商户操作指引
PENDING	PEND_RFI_MATERIAL	待补充材料	金融系统触发审查，需商户补交材料。请查看邮件或平台通知，及时上传所需文件。
PENDING	REVIEW	材料审核中	商户已提交材料，Checus 审核中，预计 0–3 个工作日反馈，无需额外操作。
PENDING	TRANSMIT	交易处理中	交易流程正常进行中，暂无阻碍，商户等待最终结果即可。

错误码说明

错误码按功能场景划分为以下几类：

分类	说明
服务端请求限制	请求频率、IP 等触发服务保护机制时返回的错误
商户配置校验	包含密钥签名、合约开通等商户接入配置校验类问题
订单信息接收	参数格式、重复订单、系统异常等提交阶段的错误
订单信息校验	包含金额限额、收款方信息验证、风控限制等
订单交易查询	查询接口相关的异常信息

错误示例同步响应示例（如发起付款时出错）：

json

{
  "msg": "Invalid account or not active",
  "code": "INVALID_ACCOUNT"
}

异步回调响应示例（如交易状态失败）：

json

{
  "appId": "4701b0a908a14312b3c8452b448256dw",
  "code": "APPLY_SUCCESS",
  "data": {
    "transactionUtcTime": "2024-08-29T12:50:38 +0000",
    "status": "FAILD",
    "responseCode": "INVALID_ACCOUNT",
    "responseMsg": "Invalid account or not active"
    // 其他字段略
  },
  "msg": "Success.",
  "notifyType": "PAYOUT"
}

服务端请求限制类错误码

错误码	错误描述	备注
REQ_TIME_OVER_TIME	requestTime effective in two minutes	请求时间与服务端偏差超过2分钟
ILLEGAL_IP_REQUEST	illegal ip request	请求IP未在白名单中，请联系 Checus 配置
TOO_MANY_REQUEST	Exceed request limitation, please retry later	接口触发限流，稍后重试

商户配置校验类错误码

子分类	错误码	错误描述	备注
签名/密钥问题	MERCHANT_APP_INVALID	Signature key is not configured.	密钥未配置
签名/密钥问题	SIGN_VERIFY_FAILED	The signature verify failed.	验签失败
合约/商户信息问题	CONTRACT_INVALID	Merchant has not signed the contract or payment methods.	未签约或未开通支付方式
合约/商户信息问题	MERCHANT_INVALID	The merchant has been offline.	商户状态异常

订单信息接收类错误码

子分类	错误码	错误描述	备注
请求参数校验问题	PARAMS_INVALID	The {field} is incorrect.	字段格式不符合要求
请求参数校验问题	ORDER_REPEAT	The order number repeat.	订单号重复
系统异常	SYSTEM_ERROR	System is busy, Please try again later.	系统繁忙，请稍后重试

订单信息校验类错误码

子分类	错误码	错误描述	备注
支付方式与金额限制问题	PAYMENT_METHOD_NOT_AVAILABLE	The payment method is not available.	支付方式不可用
		AMOUNT_LIMIT_UNMATCHED	The amount does not meet the limit requirements	交易金额不符合限额
		AMOUNT_NOT_ENOUGH	Insufficient balance	余额不足
收款账户/信息校验问题	INVALID_ACCOUNT	Invalid account or not active	收款账户无效或未激活
		ACCOUNT_BLOCKED	Account blocked or frozen	账号被冻结
		INVALID_EMAIL	Email address is incorrect.	邮箱格式错误
		MISMATCHED_NAME	Payee name does not match the account	姓名与账号不一致
二级商户信息异常问题	SUBMERCHANT_NOT_REGISTERED	The subMerchantNo is not registered	未报备二级商户或信息错误
二级商户信息异常问题		SUBMERCHANT_REGISTRATION_FAILED	The subMerchantNo registration failed	二级商户注册失败
风控拦截与其他问题	RFI_BLACKLIST	Rejected due to failure of beneficiary to submit request information	未提交合规资料
		DECLINED_BY_RISK	Beneficiary bank rejected credit	风控拒绝
		PAYMENT_FAILED	Payment failed	支付失败

订单交易查询类错误码
错误码错误描述备注
ORDER_NOT_EXIST The order does not exist. 订单不存在或正在处理中，请重新确认

收银台模式

API模式

前置组件

链接支付

Token支付

订阅支付

支付结果

退款

争议

商户管理平台出款

API模式

开始集成

环境准备

交互流程

关键接口

集成步骤

1. 创建支付会话

2. 获取支付结果

开始集成 ​

环境准备 ​

交互流程 ​

关键接口 ​

集成步骤 ​

1. 创建支付会话 ​

2. 获取支付结果 ​

开始集成

环境准备

交互流程

关键接口

集成步骤

1. 创建支付会话

2. 获取支付结果