Drop-in Integration Step - 中文

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

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

一、安装 SDK

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

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

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

二、导入SDK

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

三、设置 DropIn 组件的 HTML 容器

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

四、获取 sessionID

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

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

五、初始化 DropIn SDK

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

必要参数：

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 实现订阅场景

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

首次订阅

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

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

获取并保存 Token

支付完成后，从 webhook 回调通知或查询接口中获取 token。

将 token.value 保存到后端数据库，并与 userInfo.reference 进行关联。

后续订阅 (MIT 交易)

调用 Payment API 直接发起交易。

请求参数中需包含（详见附录 Payment API 接口）：

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

订单跟踪：使用 merchantTransID 跟踪后续订阅订单。

资金捕获：

通过 captureAfterHours 字段设置自动捕获延迟小时数（例如 "0" 表示立即捕获），字符串格式。

若未上送此字段，则需后续调用 POST /capture 接口进行手动捕获。

九、使用 Drop-in 实现保存卡片（Save Card）功能

通过 Drop-in 可让用户在支付过程中保存其卡片，以便后续无需重新输入卡信息即可复用该卡片支付。整体流程同上面的标准支付描述，仅需在对应步骤进行如下调整即可：

第一步：创建订单时开启 Save Card 功能

第四步调整（获取 sessionID）调用 LinkPay 接口时，需设置以下特殊参数，以开启 Save Card 功能并将保存的卡片与指定用户进行关联：

{
  "userInfo": {
    "reference": "your_user_reference"
  }
}

userInfo.reference：用户在您系统中的唯一标识，用于关联保存的卡片 token。

开启后，Drop-in 将在卡支付表单中展示 “Save card” 勾选框。

第二步：用户在 Drop-in 中勾选 Save Card

用户在完成支付前，于 Drop-in 卡支付表单中勾选 “Save card” 勾选框。仅当用户勾选该勾选框时，卡片才会被令牌化（tokenize）并保存。

第三步：获取并保存 Token

支付完成后，从 webhook 回调通知（第七步）或**查询接口（GET Payment API）**中获取 token。

将 token.value 保存到后端数据库，并与 userInfo.reference 进行关联。

第四步：后续使用已保存的 Token 支付

后续支付时，调用 Payment API 并携带已保存的 token 直接发起交易。请求参数中需包含（详见附录 Payment API 接口）：

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

订单跟踪：使用 merchantTransID 跟踪后续支付订单。

资金捕获：

通过 captureAfterHours 字段设置自动捕获延迟小时数（例如 "0" 表示立即捕获），字符串格式。

若未上送此字段，则需后续调用 POST /capture 接口进行手动捕获。

Drop-in Integration Step - 中文

一、安装 SDK#

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

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

二、导入SDK#

三、设置 DropIn 组件的 HTML 容器#

四、获取 sessionID#

五、初始化 DropIn SDK#

六、处理支付回调事件#

七、处理支付回调事件#

八、使用 Drop-in 实现订阅场景#

首次订阅#

后续订阅 (MIT 交易)#

九、使用 Drop-in 实现保存卡片（Save Card）功能#

第一步：创建订单时开启 Save Card 功能#

第二步：用户在 Drop-in 中勾选 Save Card#

第三步：获取并保存 Token#

第四步：后续使用已保存的 Token 支付#