开始集成

环境准备

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

环境信息如下：

测试环境	https://p-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 等触发服务保护机制时返回的错误
  商户配置校验	包含密钥签名、合约开通等商户接入配置校验类问题
  订单信息接收	参数格式、重复订单、系统异常等提交阶段的错误
  订单信息校验	包含金额限额、收款方信息验证、风控限制等
  订单交易查询	查询接口相关的异常信息

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

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

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

  {
    "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.	订单不存在或正在处理中，请重新确认