Drop-in Integration Step

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

一、接入 SDK

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

npm install cil-dropin-components
or
yarn add cil-dropin-components

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

import DropInSDK from '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/[email protected]/dist/index.min.js

二、设置 DropIn 组件的 HTML 容器

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

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

三、获取 sessionID

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

Fetch Session ID

Open Recipe

📘
Note
interaction 接口的交易认证通过请求头中的 SignKey（在请求头 Authorization 中）和 KeyID 完成。

更多参数详情介绍：见 API Explorer 中的 interaction 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 }
- 显示提示（如 “支付已取消”）

示例代码：

function handlePaymentCompleted(params) {
  const result = { type: 'payment_completed', ...params };
  displayPaymentStatus('支付成功', 'success', result);
  return result;
}

function handlePaymentFailed(params) {
  const result = {
    type: 'payment_failed',
    ...params,
    code: params.code || '错误码',
    message: params.message || '错误信息'
  };
  console.error('支付失败:', result);
  displayPaymentStatus(`支付失败: ${result.message}`, 'error', result);
  return result;
}

function handlePaymentNotPreformed(params) {
  const result = {
    type: 'payment_not_preformed',
    ...params,
    code: params.code || '响应码',
    message: params.message || '响应信息'
  };
  console.warn('支付未执行:', result);
  displayPaymentStatus('支付未执行，请重试', 'warning', result);
  return result;
}

function handlePaymentCancelled(params) {
  const result = { type: 'payment_cancelled', ...params };
  console.log('支付取消:', result);
  displayPaymentStatus('支付已取消', 'info', result);
  return result;
}

function displayPaymentStatus(message, statusType, result) {
  const statusEl = document.getElementById('status');
  statusEl.innerHTML = `
    <div style="padding: 16px; border: 1px solid">
      <h3>${message}</h3>
      <p>类型: ${result.type}</p>
      ${result.merchantTransID ? `<p>商户交易 ID: ${result.merchantTransID}</p>` : ''}
      ${result.sessionID ? `<p>Session ID: ${result.sessionID}</p>` : ''}
      ${result.code ? `<p>错误码: ${result.code}</p>` : ''}
      ${result.message ? `<p>信息: ${result.message}</p>` : ''}
    </div>
  `;
}

六、处理支付回调事件

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

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

Notification from Webhook

Open Recipe

📘
Note
收到通知后，需返回纯文本 SUCCESS 表示接收成功。若未收到响应信息，系统会按照规定的频率（15/15/30/180/1800/1800/1800/1800/3600. 单位：秒）定期重新发送异步通知，直到成功收到 SUCCESS 或通知次数达到上限。

参数详见 API Explorer interaction Notification。

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

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

首次订阅

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

{
  "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 接口进行手动捕获。

Subscription Payment

Open Recipe

八、可选接口

查询支付状态 (GET)

通过 GET /payment/{merchantTransID} 接口查询支付状态。merchantTransID 需从支付响应或异步通知中的 payment.merchantTransInfo.merchantTransID 中获取。

捕获 (Capture)

对于 authorized 状态的交易，可通过 POST /payment/{merchantTransID}/capture 完成最终扣款。

退款 (Refund)

通过 POST /payment/{merchantTransID}/refund 接口对已经完成支付的订单发起全额或者部分退款。