开始集成

环境准备

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

环境信息如下：

测试环境	https://pay-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. 注册开发者中心账号并开通支付方式
2. 配置支付结果通知回调（notifyUrl）
3. 获取商户公钥、平台公钥、AppID 等信息
4. 设置测试环境 IP 白名单
5. 了解签名机制（加签与验签）
6. 使用 支付创建接口/orderAndPay API 发起首次支付
7. 接收异步通知或调用 交易查询/orderQuery API
8. 记录返回的 PaymentTokenID 用于后续支付

核心流程

创建支付

• 接口：支付创建接口/orderAndPay API
• 支付方式：首次支付使用指定CARD支付方式进行支付；后续支付可使用 PaymentTokenID

通用参数说明

使用Token支付，支付创建接口/orderAndPay API请求中都应包含以下基本字段：

• outTradeNo: 商户系统订单号（唯一）
• totalAmount: 金额
• currency: 币种
• country: 用户所在国家
• userId: 用户标识
• frontCallbackUrl: 支付完成后跳转地址
• notifyUrl: 支付结果通知回调（可在商户管理平台统一配置）
• integrate: 固定为 Hosted_Checkout
• expireTime: 关单时间，单位为秒。默认区间：1800~86400，不在区间内将被强制修正。
• paymentMethodType: 支付方式类型，固定为 "CARD"
• allowedCardOrg: 可选，允许的卡品牌，如 [ "VISA", "MASTERCARD" ]，为空表示允许所有卡
• tokenForFutureUse: 可选，是否启用 Token 支付（Token支付必传，且值为"true"）
• paymentTokenID: 支付 Token，仅首次支付后返回，用于后续免敏支付

响应

• tradeToken：Checus 交易单号
• redirectUrl：返回收银台URL，用户需要在Checus收银台页面输入银行卡信息
• status：订单状态（PENDING / SUCCESS）
• 无需3DS验证（用户后续支付传递paymentTokenID时）：
  • 系统直接返回 status=SUCCESS，同时返回 tradeToken 和 outTradeNo。
  • 不会返回 redirectUrl
  • 商户可认为支付成功，但仍需通过通知或查询进行确认。
• 需3DS验证流程（用户首次支付tokenForFutureUse 为true和后续支付传递paymentTokenID时）：
  • 系统返回 status=PENDING 及 redirectUrl。
  • 商户重定向用户至Checus 收银台页面。
  • 用户完成验证后，Checus 更新订单状态为成功。
  • 商户通过回调或查询确认最终结果。

关键提示：

• 不要仅依赖 支付创建接口/orderAndPay API 返回状态更新本地订单。
• 无论3DS与否，tradeToken 与 outTradeNo 均会返回。

获取支付结果

请查阅 支付结果集成。

使用 PaymentTokenID 支付

• 后续支付无需卡信息，直接在支付创建接口/orderAndPay API 中传 userId + PaymentTokenID 即可完成扣款

PaymentTokenID 查询

商户可以通过paymentTokenID查询/inquirePaymentToken API 接口来查询某用户绑定的所有PaymentTokenID

调用方向： 商户 → Checus

接口地址： /inquirePaymentToken

请求关键字段：

• userId：用户标识
• tokenScope：固定值 "tokenAcq"
• paymentMethodType：支付方式类型（可选）
• cardOrg：卡品牌（CARD 时可选）
• paymentTokenID：指定查询某个 Token（可选）

PaymentTokenID 解绑

当用户希望移除绑定的 Token，商户可通过paymentTokenID解绑/removePaymentToken API 接口删除 Token。解绑后，Token 将无法再用于支付。

调用方向： 商户 → Checus

接口地址： /removePaymentToken

请求关键字段：

• userId：用户标识
• paymentTokenID：待解绑 Token
• removeReason：解绑原因

交互流程

关键接口

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

集成步骤

1. 注册开发者中心账号并开通支付方式
2. 配置支付结果通知回调（notifyUrl）
3. 获取商户公钥、平台公钥、AppID 等信息
4. 设置测试环境 IP 白名单
5. 了解签名机制（加签与验签）
6. 使用支付创建接口/orderAndPay API 发起首次支付
7. 接收异步通知或调用 交易查询/orderQuery API
8. 记录返回的 PaymentTokenID 用于后续支付

核心流程

创建支付

• 接口：支付创建接口/orderAndPay API
• 支付方式：
  • 首次支付：使用指定 CARD 支付方式完成支付；系统返回 PaymentTokenID。
  • 后续支付：可使用 PaymentTokenID完成扣款，无需重新输入卡信息。

通用参数说明

使用Token支付，支付创建接口/orderAndPay API请求中都应包含以下基本字段：

• outTradeNo： 商户系统订单号（唯一）
• totalAmount： 金额
• currency： 币种
• country： 用户所在国家
• userId： 用户标识
• frontCallbackUrl： 支付完成后跳转地址
• notifyUrl： 支付结果通知回调（可在商户管理平台统一配置）
• integrate： 固定为 Direct_Payment
• expireTime： 关单时间，单位为秒。默认区间：1800~86400，不在区间内将被强制修正。
• paymentMethodType： 支付方式类型，固定为 "CARD"
• allowedCardOrg： 可选，允许的卡品牌，如 [ "VISA", "MASTERCARD" ]，为空表示允许所有卡
• tokenForFutureUse： 可选，是否启用 Token 支付（Token支付必传，且值为"true"）
• paymentTokenID： 支付 Token，仅首次支付后返回，用于后续免敏支付

响应参数

• tradeToken：Checus 交易单号
• redirectUrl：如需 3DS 验证，返回3DS URL
• status：订单状态（PENDING / SUCCESS）
• 无需 3DS 验证流程：
  • 系统直接返回 status=SUCCESS，同时返回 tradeToken 和 outTradeNo。
  • 不会返回 redirectUrl
  • 商户可认为支付成功，但仍需通过通知或查询进行确认。
• 需 3DS 验证流程：
  • 系统返回 status=PENDING 及 redirectUrl。
  • 商户重定向用户至 3DS 验证页面。
  • 用户完成验证后，Checus 更新订单状态为成功。
  • 商户通过回调或查询确认最终结果。

关键提示：

• 不要仅依赖 支付创建接口/orderAndPay API 返回状态更新本地订单。
• 无论3DS与否，tradeToken 与 outTradeNo 均会返回。

获取支付结果

请查阅 支付结果集成。

PaymentTokenID 查询

商户可以通过paymentTokenID查询/inquirePaymentToken API 接口来查询某用户绑定的所有PaymentTokenID

调用方向： 商户 → Checus

接口地址： /inquirePaymentToken

请求关键字段：

• userId：用户标识
• tokenScope：固定值 "tokenAcq"
• paymentMethodType：支付方式类型（可选）
• cardOrg：卡品牌（CARD 时可选）
• paymentTokenID：指定查询某个 Token（可选）

PaymentTokenID 解绑

当用户希望移除绑定的 Token，商户可通过paymentTokenID解绑/removePaymentToken API 接口删除 Token。解绑后，Token 将无法再用于支付。

调用方向： 商户 → Checus

接口地址： /removePaymentToken

请求关键字段：

• userId：用户标识
• paymentTokenID：待解绑 Token
• removeReason：解绑原因

交互流程

关键接口

关联交互时序	调用方向	接口类型	接口名称/方法
1.3 获取前置组件初始化信息	商户 -> Checus	后端接口	/applyDropinSession
1.6 创建并挂载Checus组件	商户客户端 -> Checus前置组件JS SDK	前端接口	PMdropin.create
1.6 创建并挂载Checus组件	商户客户端 -> Checus前置组件JS SDK	前端接口	PMdropin.mount
1.6 创建并挂载Checus组件	商户客户端 -> Checus前置组件JS SDK	前端接口	PMdropin.on
2.2 获取paymentToken	商户客户端 -> Checus前置组件JS SDK	前端接口	PMdropin.emit
3.4 创建支付，调用前置组件下单接口	商户 -> Checus	后端接口	/orderAndPay
4.1 支付结果异步通知	Checus -> 商户	后端接口	/collectResultNotifyUrl
5.1 查询支付交易	商户 -> Checus	后端接口	/orderQuery

卡类支付集成步骤

1. 创建支付会话

调用 前置组件初始化 API ，发起POST请求以创建支付。

从返回值获取 clientKey 和 sessionKey，用于前端组件初始化。

{
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <参考：https://docs-v2.checus.com/doc-center/developer/config-settings.html>
};

request.body =
    {
        "version": "1.1",
        "keyVersion": "1",
        "requestTime": <替换>,
        "merchantNo": <替换>,
        "appId": <替换>,
        "data": {
            "country": "ID",
            "currency": "IDR",
            "totalAmount":"50",
            "userId": "20251025_0834",
            "tokenForFutureUse": true, # 传true，则表示该笔请求Token支付请求，组件上会显示Token协议
            "componentList":["APPLEPAY","CARD"]
        }
    }

response={
  "msg": "",
  "code": "APPLY_SUCCESS",
  "data": {
    "sessionKey": "bf2c47b085e24c299e45dd56fd751a70",
    "clientKey": "bbd8d2639a7c4dfd8df7d005294390df"
    }
}

2. 渲染组件

您可下载 Demo示例，替换 clientKey 和 sessionKey 后可以本地打开看到效果。

• 引入 JS 组件

  <script src="https://dropin.checus.com/dropin/js/pmdropin.min.js"></script>

• 添加挂载容器

  <div class="frame-card">
      <!-- form will be added here -->
  </div>

• 初始化组件

  // 初始化卡组件
  const card = PMdropin.create('card', {
    clientKey: "客户端公钥", // 在步骤1中获取到的 data.clientKey
    sessionKey: "会话令牌", // 在步骤1中获取到的 data.sessionKey
    sandbox: false, // 默认是 false，即生产环境
    hideSaveCard: false, //是否隐藏保存卡信息选项，默认是false展示
    hideCardBrands: false, //是否隐藏左上角卡品牌的Logo，默认是false展示
  });
  // 挂载实例
  card.mount('.frame-card'); // 将挂载至匹配到的第一个dom元素上
  // 组件加载完成时机
  card.on('ready', () => {
      // 移除自定义loading
  })

• 监听表单状态（可选）

状态变更时将实时回调，可以由此决定支付按钮是否可点击。

card.on('form-check', (res) => {
  // res.isFormValid 为表单状态 false/true
  // true 表示表单校验通过,可尝试支付；false 表示校验未通过，无法点击支付按钮
  console.log('[dropin][form-check]:', res)
})

• 勾选token支付协议

不勾选Token支付协议，会走到普通支付流程，支付完成后，不会返回商户PaymentTokenID；只有用户勾选Token协议后，支付完成后，才会返回商户PaymentTokenID。

• 获取支付 token 并发起下单

调用支付接口前务必检查是否可支付；可支付时，将获取到 paymentToken, 用于发起支付接口。

  card.emit('setDisabled', true) // 点击支付按钮后冻结表单，防止重复提交支付过程
  card.emit('canMakePayment')
    .then(res => {
      if (res.code === 'APPLY_SUCCESS') {
        const paymentToken = res.data.paymentToken // 支付token，支付接口使用
        // 发起支付接口
        // 商户自己请求后端接口进行下单, 
        // 商户自己用params构造请求参数，需要带上paymentToken。
        // res.data.agreementAccepted = true，表示用户勾选了token协议，
        // res.data.agreementAccepted = false，表示用户未勾选了token协议，
        // 只有res.data.agreementAccepted=true时，商户在调用orderAndPay接口时
        // 才能上送data.paymentDetail.tokenForFutureUse=true，否则下单会失败
          _postapi('orderAndPay',params).then(res =>{
            const code = (res || {}).code
            //商户将支付结果返回到前端
            if (code == 'APPLY_SUCCESS') {     
              //支付成功，展示支付结果
            } else {
              //支付失败，展示支付结果
            }
      }
        card.emit('setDisabled', false) // 支付接口完成后解冻表单
      }
    })
    .catch(err => {
      card.emit('setDisabled', false) // 发生异常后解冻表单
    })

3. 商户后台下单

发起时机

当 canMakePayment 返回 APPLY_SUCCESS 后，从中获取 paymentToken，由商户服务端调用 /orderAndPay 接口完成下单。

请求流程

• 商户前端将 paymentToken 传至商户后端；首次支付唤起前置组件进行支付，后续支付可使用 PaymentTokenID
• 商户服务端生成唯一 outTradeNo，向 Checus 发起支付请求；

响应

• tradeToken：Checus 交易单号
• redirectUrl：如需 3DS 验证，返回收银台 URL
• status：订单状态（PENDING / SUCCESS）
• 无需 3DS 验证
  • 创建支付后，系统直接返回交易状态为“成功”，同时返回 tradeToken 和 outTradeNo。
  • 不会返回 redirectUrl
  • 商户可根据返回的状态确认支付完成，无需额外跳转或验证。
• 需 3DS 验证
  • 创建支付后，系统返回交易状态为“待处理”，并提供一个 3DS 验证页面的跳转链接。
  • Checus收银台会将用户重定向至该 3DS 页面完成验证。
  • 用户完成验证后，支付状态会更新，商户可通过支付结果通知或订单查询确认最终状态。

关键提示：

• 不要仅依赖 支付创建接口/orderAndPayAPI 返回状态更新本地订单。
• 无论3DS与否，tradeToken 与 outTradeNo 均会返回。

下单详细字段请参与 前置组件支付接口。

  {
    'Content-Type': 'application/json;charset=utf-8',
    'Accept': 'application/json',
    'sign': <XXX>
  };

  {
    "appId": <替换>,
        "version": "1.4",
        "merchantNo": <替换>,
        "requestTime": "2024-06-05T10:46:01.694+08:00",
        "keyVersion": "1",
        "data": {
                "totalAmount": 77.44,
                "country": "HK",
                "expireTime": "7200",
                "paymentDetail": {
                        "paymentMethodType": "CARD",
                        "paymentToken": "332e4cc1af1740aeafe9e7df82aeb5a1",
                        "buyerInfo": {
                                "clientIp": "59.82.59.92",
                                "userAgent": "Chrome"
                        },
                        "sessionKey": "86409e2c04b44536a484caa5ce3ce0e9"
                },
                "frontCallbackUrl": <替换>,
                "subject": "GoGeal PTE. LTD.",
                "outTradeNo": <商户订单号，需唯一>,
                "notifyUrl": <替换>,
                "currency": "HKD",
                "userId": "3ff0495692d152be96d84dbc9352dc57",
                "integrate": "Direct_Payment",
                "terminalType": "WEB"
        }
  }

4. 获取支付结果

请查阅 支付结果集成。

5. 使用 PaymentTokenID 支付

• 后续支付无需卡信息，直接在支付创建接口/orderAndPay API 中传 userId + PaymentTokenID 即可完成扣款

6. PaymentTokenID 查询

商户可以通过paymentTokenID查询/inquirePaymentToken API 接口来查询某用户绑定的所有PaymentTokenID

调用方向： 商户 → Checus

接口地址： /inquirePaymentToken

请求关键字段：

• userId：用户标识
• tokenScope：固定值 "tokenAcq"
• paymentMethodType：支付方式类型（可选）
• cardOrg：卡品牌（CARD 时可选）
• paymentTokenID：指定查询某个 Token（可选）

7. PaymentTokenID 解绑

当用户希望移除绑定的 Token，商户可通过paymentTokenID解绑/removePaymentToken API 接口删除 Token。解绑后，Token 将无法再用于支付。

调用方向： 商户 → Checus

接口地址： /removePaymentToken

请求关键字段：

• userId：用户标识
• paymentTokenID：待解绑 Token
• removeReason：解绑原因

卡类前端接口

API 使用说明

前置组件提供了标准的 API 接口供前端调用，核心方法通过 PMdropin.API 调用。

方法	描述	说明
create	初始化组件	详见 1.1
mount	挂载组件至页面	详见 1.2
on	监听组件事件	详见 1.3
emit	触发组件方法	详见 1.4

1. create — 初始化组件

const card = PMdropin.create('card', options);

• ComponentName：当前支持 'card'（卡支付）
• options 参数如下：

参数	类型	必填	默认值	描述
clientKey	string	✅	-	客户端公钥
sessionKey	string	✅	-	会话令牌
sandbox	boolean	❌	false	是否启用沙盒环境
language	string	❌	'en'	显示语言
theme	string	❌	'light'	默认主题
customLocalization	object	❌	-	自定义语言包
customTheme	object	❌	-	自定义样式
grayscale	string	❌	'0'	页面灰度（0-1）
isRtl	boolean	❌	false	从右至左布局支持
hideSaveCard	boolean	❌	false	是否隐藏“保存卡”选项
hideCardBrands	boolean	❌	false	是否隐藏卡组织 Logo
hideCardHolderName	boolean	❌	false	是否隐藏姓名输入框
saveCardChecked	boolean	❌	true	“保存卡”默认是否勾选
ignoreUserCheckedCache	boolean	❌	false	忽略用户勾选缓存

2. mount — 挂载组件

card.mount('#card-frame');  // 挂载到指定 DOM 节点

支持使用 id 或 class 选择器。

3. on — 监听组件事件

card.on('ready', () => {
  // 组件加载完成
});

card.on('form-check', (res) => {
  if (res.isFormValid) {
    // 表单校验通过，可启用支付按钮
  }
});

事件名	说明
ready	组件加载完成
form-check	实时返回表单是否校验通过（res.isFormValid = true/false）

4. emit — 调用组件方法

常用事件

方法	参数	说明
canMakePayment	-	校验表单并获取 paymentToken
setDisabled	boolean	启用/禁用表单交互
switchLanguage	string	切换语言
switchTheme	string	切换主题
addLocalization	object	添加自定义语言包
addTheme	object	添加自定义主题
setRtl	boolean	启用 RTL 布局
setGrayscale	string	设置页面灰度（0-1）

4.1 canMakePayment — 校验表单并获取 paymentToken

card.emit('canMakePayment')
  .then(res => {
    if (res.code === 'APPLY_SUCCESS') {
      const paymentToken = res.data.paymentToken;
      // 使用 token 发起后端支付
    }
  })
  .catch(err => {
    console.error('支付失败：', err);
  });

返回结构

// 成功
{
  code: 'APPLY_SUCCESS',
  data: {
    paymentToken: 'xxx'
  },
  msg: ''
}

// 失败
{
  code: 'FORM_INVALID',  // 或 UNKNOWN_ISSUE
  msg: 'Invalid params: cvv'
}

返回码	说明
APPLY_SUCCESS	成功获取 paymentToken
FORM_INVALID	表单未通过校验
UNKNOWN_ISSUE	其他异常错误

4.2 - 4.8 其他 emit 用法示例

更多配置请参考 卡类定制化

// 设置表单为不可编辑状态
card.emit('setDisabled', true);

// 切换语言
card.emit('switchLanguage', 'zh-CN');

// 启用右至左布局
card.emit('setRtl', true);

// 设置页面灰度为 100%
card.emit('setGrayscale', '1');

卡类定制化

通过定制语言和主题样式，您可以更好地适配自身网站的 UI 和用户体验。

1. 语言本地化

1.1 使用预置语言

支持设置 language 参数快速切换语言：

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  language: 'zh' // zh: 中文, en: 英文（默认）
});

也可通过如下方式动态切换：

PMdropin.emit('switchLanguage', 'zh');

1.2 自定义语言

如预置语言不满足需求，可通过 customLocalization 添加自定义字段：

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  customLocalization: {
    // 添加中文示例
    'zh': {
      loading: '加载中',
      loadingFailed: '加载失败',
      refresh: '刷新',
      confirm: '确定',
      cancel: '取消',
      removeCard: '移除卡',
      removeCardTip: '确定移除当前选中卡吗?',
      addNewCard: '使用新卡',
      useSavedCard: '使用已存卡',
      cardnum: '银行卡号',
      cardnumHint: 'XXXX XXXX XXXX XXXX',
      cardnumErrTip: '卡号不正确',
      cardbinErrTip: {
        // {cardOrg} 变量字段，无需翻译
        CARD_NOT_SUPPORT: '不支持{cardOrg}，请检查卡号或者更换其他卡重试',
        // {cardType} 变量字段，无需翻译
        CARD_INVALID: '不支持{cardType}的卡类型',
        CARD_NO_INVALID: '请确认卡号输入是否正确',
      },
      expdate: '过期日期',
      expdateHint: '月/年',
      expdateErrTip: '过期日期不正确',
      cvv: 'CVV/CVC',
      cvvHint: '123',
      cvvErrTip: 'CVV/CVC 格式不正确',
      name: '持卡人姓名',
      nameHint: 'XX XX',
      nameErrTip: '姓名格式不正确',
      saveCardInfoTip: '为下次支付保存信息',
      // 以下为新增多语言字段
      // 本地卡额外采集要素
      buyerEmail: '邮箱',
      buyerEmailHint: '',
      buyerEmailErrTip: '格式错误，请复核',
      buyerFullName: '姓名',
      buyerFullNameHint: '',
      buyerFullNameErrTip: '格式错误，请复核',
      buyerFirstName: '名',
      buyerFirstNameHint: '',
      buyerFirstNameErrTip: '格式错误，请复核',
      buyerLastName: '姓',
      buyerLastNameHint: '',
      buyerLastNameErrTip: '格式错误，请复核',
      // 秘鲁 Document(ID)
      dni: 'DNI',
      dniHint: '',
      dniErrTip: '格式错误，请复核',
      // 阿根廷 Document(ID)
      dni_cuit: 'DNI/CUIT',
      dni_cuitHint: '',
      dni_cuitErrTip: '格式错误，请复核',
      // 南非 Document(ID)
      idCard: 'ID',
      idCardHint: '',
      idCardErrTip: '格式错误，请复核',
      // 哥伦比亚 Document(ID)
      cc: 'CC',
      ccHint: '',
      ccErrTip: '格式错误，请复核',
      // 墨西哥 Document(ID)
      curp: 'CURP',
      curpHint: '',
      curpErrTip: '格式错误，请复核',
      // 巴西 Document(ID)
      cpf: 'CPF',
      cpfHint: '',
      cpfErrTip: '格式错误，请复核',
      // 智利/巴拉圭/乌拉圭 Document(ID)
      ci: 'CI',
      ciHint: '',
      ciErrTip: '格式错误，请复核',
      buyerPhoneNo: '手机号码',
      buyerPhoneNoHint: '',
      buyerPhoneNoErrTip: '格式错误，请复核',
      buyerPhoneNoRegion: '手机区号',
      buyerPhoneNoRegionHint: '',
      buyerPhoneNoRegionErrTip: '格式错误，请复核',
    }
  },
  ...
});

动态添加方式：

PMdropin.emit('addLocalization', {
  'zh': {
    // 参数如上所示
  }
});

2. 主题样式

2.1 使用预置主题

支持 light（默认）与 dark 两种主题：

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  theme: 'dark'
});

动态切换：

PMdropin.emit('switchTheme', 'dark');

2.2 自定义主题

可通过 customTheme 自定义 CSS 变量覆盖主题样式：

PMdropin.create('card', {
  clientKey: '',
  sessionKey: '',
  customTheme: [
    {
      name: 'red',
      base: 'light',
      style: `:root {
        --color-primary: #e60000;
        --bg-primary: #fff;
        --border-radius-primary: 8px;
        // ... 其他样式
      }`
    }
  ]
});

也可通过动态添加：

PMdropin.emit('addTheme', [{ name: 'red', base: 'light', style: '...' }]);