Drop-in Integration Step

本指南面向开发者，详细说明如何通过 Drop-in 集成线上支付功能，支持支付订阅等场景。

集成流程的核心步骤与数据流向如下图所示，您可根据实际需求灵活参与其中的模块：

一、安装 SDK

方式一：使用 npm 或 yarn 将 cil-dropin-components SDK 安装为项目的依赖项。

npm

npm install cil-dropin-components

yarn

yarn add cil-dropin-components

方式二：通过 CDN 的方式拉取 JS 资源

建议在拉取失败时使用我们提供的 index.min.js 进行保底。

始终保持最新版本
https://cdn.jsdelivr.net/npm/cil-dropin-components@latest/dist/index.min.js

指定版本
https://cdn.jsdelivr.net/npm/cil-dropin-components@1.0.4/dist/index.min.js

二、导入 SDK

在前端代码中导入 DropInSDK，以便在页面中使用其功能。导入方式因技术栈而异。

import DropInSDK from 'cil-dropin-components'

三、设置 DropIn 组件的 HTML 容器

在前端页面中添加一个容器元素，用于渲染 DropIn 组件，例如：

<div id="dropInApp"></div>

四、获取 sessionID

在初始化 DropInSDK 之前，必须先获取 sessionID。后端通过调用 LinkPay API 响应中获取 sessionID，需提取并传递给前端的 DropInSDK。

更多参数详情介绍：见 API Explorer 中的 LinkPay API 接口详情。

五、初始化 DropIn SDK

使用从上一步中获取的 sessionID 及其他必要参数初始化 DropInSDK，以渲染支付界面并处理用户交付：

const sdk = new DropInSDK({
  id: '#dropInApp',
  type: 'payment',
  sessionID: 'your-session-id',
  locale: 'en-US',
  mode: 'embedded',
  environment: 'UAT',
  appearance: {
    colorBackground: '#fff'
  },
  payment_completed: handlePaymentCompleted,
  payment_failed: handlePaymentFailed,
  payment_not_preformed: handlePaymentNotPreformed,
  payment_cancelled: handlePaymentCancelled
})

必要参数：

• id：容器 CSS 选择器
• type：组件类型
• sessionID：从支付 API 获取的唯一 sessionID
• locale：界面语言代码（如 'en-US'、'zh-CN'）
• mode：显示模式（'embedded' 或 'fullPage'）
• environment：SDK 发送请求的环境（如 'UAT' 代表 Sandbox，'HKG_prod' 代表生产）

可选参数：

• appearance：自定义界面样式
• 回调函数：见下一步
• 其他参数：参考 SDK reference 文档获取更多配置选项

六、处理支付回调事件

处理 DropInSDK 返回的支付回调，记录关键数据（如 merchantTransID），更新 UI，并触发后续操作。

• payment_completed：支付成功时触发 返回：{ type: 'payment_completed', merchantTransID, sessionID }

  • 记录 merchantTransID（用于后续查询订单详情或退款）
  • 更新 UI 显示 “支付成功”

• payment_failed：支付失败时触发 返回：{ type: 'payment_failed', merchantTransID, sessionID, code, message }

  • 记录 merchantTransID、code 和 message（用于调试）
  • 显示错误提示（如 “支付失败：{message}”）

• payment_not_preformed：支付未执行时触发（如用户未完成支付流程） 返回：{ type: 'payment_not_preformed', merchantTransID, sessionID, code, message }

  • 记录 merchantTransID 和 code
  • 显示提示（如 “支付未完成，请重试”）

• payment_cancelled：用户取消支付时触发 返回：{ type: 'payment_cancelled', sessionID }

  • 显示提示（如 “支付已取消”）

七、处理支付回调事件

设置第四步中 webhook 端点接收 Evonet 的异步通知。通知通常包含以下字段：

• result: 订单结果
• merchantOrderID: 用于查询订单状态
• merchantTransID: 用于退款等操作
• status: 订单状态码，用于更新数据库订单状态
• 其他元数据：时间、金额等

更多参数详情介绍：见 API Explorer 中的 LinkPay API 接口详情。

八、使用 Drop-in 实现订阅场景(Coming)

通过 Drop-in 可实现订阅支付场景，整体流程同上面的描述，仅需在对应步骤进行如下调整即可：

首次订阅

1. 第四步调整（获取 sessionID） 调用 LinkPay 接口时，需设置以下特殊参数：

{
  "userInfo": {
    "reference": "your_user_reference"
  },
  "paymentMethod": {
    "recurringProcessingModel": "Subscription"
  }
}

2. 获取并保存 Token
   • 支付完成后，从 webhook 回调通知或查询接口中获取 token。
   • 将 token.value 保存到后端数据库，并与 userInfo.reference 进行关联。

后续订阅 (MIT 交易)

• 调用 Payment API 直接发起交易。
• 请求参数中需包含（详见附录 Payment API 接口）：

{
  "paymentMethod": {
    "token": {
      "value": "之前保存的token值"
    },
    "recurringProcessingModel": "Subscription"
  }
}

• 订单跟踪：使用 merchantTransID 跟踪后续订阅订单。
• 资金捕获：
  • 通过 captureAfterHours 字段设置自动捕获延迟小时数（例如 "0" 表示立即捕获），字符串格式。
  • 若未上送此字段，则需后续调用 POST /capture 接口进行手动捕获。