# Dropin Components
## Installation
```bash
npm install cil-dropin-components
or
yarn add cil-dropin-components
```
## Usage
```js
html:
js:
import DropInSDK from 'cil-dropin-components'
const sdk = new DropInSDK({
id: '#dropInApp'
payment_completed: (ret) => {
// 接收Event，支付成功回调
},
// 你可以在这里传递更多参数，参考 Options
})
// 销毁示例
sdk.destroy()
```
## Options
| Option | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- |
| id | string | Yes | 挂载的 DOM 元素 ID |
| type | string | Yes | 固定值： payment |
| sessionID | string | Yes | 取 interaction 接口返回的 sessionID |
| locale | string | Yes | Drop-in 显示的语言
例：`en-US` |
| environment | string | Yes | 设置 Drop-in 应指向并发送请求的环境
枚举值：`HKG_prod` `BKK_prod` `TYO_prod` `UAT` `SANDBOX` `REG` `TEST` |
| mode | string | Yes | 设置 Drop-in UI 展示模式
枚举值：`fullPage` `embedded` `bottomUp` |
| uiOption | object | No | 接入方可以通过本字段定义 Drop-in 页面中的元素展示 |
| appearance | object | No | 接入方可以通过本字段定义 Drop-in 的 UI 样式 |
| verifyOption | object | No | 接入方可以通过本字段定义是否接收 Cardbin 检查的 Event( payment_method_selected )
| returnUrl | string | No | 支付回调地址 |
### uiOption object
| Option | Type | Required | Description |
| ----------------- | ------- | -------- | ------------------------------------------------------ |
| showSaveImage | boolean | No | 控制页面上是否展示保存支付方式详情的按钮，不传默认 false |
| card | object | No | 卡支付相关元素的控制 |
| TnC | object | No | TnC 相关元素的控制 |
| customDescription | object | No | 自定义文案及展示相关控制 |
### card object
| Option | Type | Required | Description |
| ------------------ | ------- | -------- | --------------------------------------------------------------------------------- |
| showCardHolderName | boolean | No | 控制页面上是否收集持卡人姓名输入框，如果不传，默认为 false 不展示持卡人姓名输入框 |
| CVVForSavedCard | boolean | No | 控制页面上是否在使用 Saved card 支付时还需要输入 CVV，不传默认为 false |
| showScanCardButton | boolean | No | 控制页面上是否展示识别卡号的按钮 |
### TnC object
| Option | Type | Required | Description |
| ------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| showTnC | boolean | No | 控制页面上是否展示 TnC
如果不传，默认为 false 不展示 TnC |
| mode | boolean | No | 控制页面上如何展示 TnC
枚举值：
`checkbox`：TnC 前展示 checkbox
`click2accept`：TnC 前没有 checkbox，点击 Pay 按钮即表示接受 TnC
默认值：`click2accept` |
| url | string | conditional | 商户提供的 TnC 的页面地址，当 displayTnC = true 时必填 |
### customDescription object
| Option | Type | Required | Description |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| freeTrialDescription | string | No | 自定义免费试用（0 元订阅）场景下的提示文案，不传使用默认文案 |
| freeTrialBtnText | string | No | 自定义免费试用（0 元订阅）场景下的支付按钮文案，不传使用默认文案
| payBtnText | string | No | 自定义支付按钮文案，不传使用默认文案
| hidePayAmount | boolean | No | 自定义是否隐藏支付金额
| saveCardDescription | string | No | 自定义绑卡提示文案，不传使用默认文案
| subscribeBtnText | string | No | 自定义支付并订阅按钮文案，不传使用默认文案
| subscribeDescription | string | No | 自定义订阅支付提示文案，不传使用默认文案
| hideSubscribeAmount | boolean | No | 自定义是否隐藏支付并订阅金额 |
| nonAmount | boolean | No | 控制是否隐藏金额提示（仅 0 元场景生效）
传 `true` 时不展示总金额，不传或 `false` 时正常展示总金额 |
| failedButtonTips | string | No | 自定义 GooglePay / ApplePay 不可用（SDK 加载失败，或设备/浏览器不支持）时占位按钮的文案，不传使用默认国际化文案“暂时无法使用” |
### appearance object
| Option | Type | Required | Description |
| ---------------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mutilKey | string | No | 用于同时控制 input text, error messages, total amounts, modal content, popup message 五个字段的字体。优先级：单个配置 > mutilKey |
| colorAction | string | No | Checkbox 选中或按钮可点击的状态的颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorBackground | string | No | 整个 Drop-in 的背景颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorBoxStroke | string | No | 边框、分割线、输入框边框颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorDisabled | string | No | 按钮不可点击时的颜色颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorError | string | No | Checkbox, 输入框报错的时边框以及 error 提示文字的颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorFormBackground | string | No | Checkbox, 输入框的背景色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorFormBorder | string | No | 输入框边框颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorInverse | string | No | 按钮中文字的颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorBoxFillingOutline | string | No | 输入框的边框选状态下的颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorPlaceholder | string | No | 输入框占位符的颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorPrimary | string | No | 主字体颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| colorSecondary | string | No | 副字体颜色，具体关联的 UI 见设计图
十六进制颜色码，例如：#5E48FC |
| button | font object | No | 控制按钮样式，具体关联的 UI 见设计图 |
| heading | font object | No | 控制标题样式（同时用于弹窗标题），具体关联的 UI 见设计图 |
| subHeading | font object | No | 控制父标题样式，具体关联的 UI 见设计图 |
| label | font object | No | 控制标签样式，具体关联的 UI 见设计图 |
| labelInfo | font object | No | 控制文字标题样式（同时用于弹窗文字标题、弹窗文字内容、详情文字），具体关联的 UI 见设计图 |
| inputField | font object | No | 控制文本框中文字样式，具体关联的 UI 见设计图 |
| paragraph | font object | No | 控制注脚样式，具体关联的 UI 见设计图 |
| placeholder | font object | No | 控制文本框中占位符样式，具体关联的 UI 见设计图 |
| borderRadius | array | No | 控制页面圆角大小，具体关联的 UI 见设计图
["4px", "8px", "10px", "8px"]
以上四个数据分别表示 `borderRadius 1` `borderRadius 2` `borderRadius 3` `borderRadius 4` |
| logoPosition | string | No | 控制商户 logo 位置，具体关联的 UI 见设计图
枚举值：`left` `middle` `right` |
### font Object
| Option | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
| fontFamily | string | Yes | 字体
例：`-apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif` |
| fontSize | string | Yes | 字体大小
例：`16px` |
| fontWeight | string | Yes | 字体粗细
例：`400` |
| letterSpacing | string | Yes | 字间距
例：`0.3px` |
| lineHeight | string | Yes | 行高
例：`1.5` |
### verifyOption object
| Option | Type | Required | Description |
| -------------------- | ------- | -------- | ----------------------------------------------------------- |
| isVerifyPaymentBrand | boolean | No | 控制接入否接收 cardbin 检查的 Event，如果不传，默认为 false |
| maxWaitTime | number | No | 控制接收 cardbin 检查的 Event的最大等待时间，如果不传，默认为 10(s) |
## Event
Drop-in 通过向接入方页面发送事件消息来响应命令。发出命令的客户端监听事件消息。
### payment_completed
当用户在 Drop-in 中完成支付并且支付结果为成功时返回此 event
| Option | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------- |
| type | string | Yes | 固定值 payment_completed |
| sessionID | string | Yes | 同调用 Drop-in 时的 sessionID |
| merchantTransID | string | Yes | 交易订单号，可以使用 GET Payment API 查询详情 |
| econtext | object | No | 需要展示支付信息独立支付的支付方式时返 |
### payment_failed
当用户在 Drop-in 中完成支付但是支付结果为失败时返回此 event
| Option | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------- |
| type | string | Yes | 固定值 payment_failed |
| sessionID | string | Yes | 同调用 Drop-in 时的 sessionID |
| merchantTransID | string | Yes | 交易订单号，可以使用 GET Payment API 查询详情 |
| code | string | No | 支付失败是联机返回的应答码 |
| message | string | No | 支付失败是联机返回的应答内容 |
### payment_not_preformed
在商户页面调用 Drop-in 时发生错误返回此 event。例如 payment command 中 sessionID 不存在或错误。
| Option | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------- |
| type | string | Yes | 固定值 payment_not_preformed |
| sessionID | string | Yes | 同调用 Drop-in 时的 sessionID |
| code | string | No | 应答码见下方表格 |
| message | string | No | 应答码见下方表格 |
### payment_method_selected
在商户开启 Cardbin 校验时（isVerifyPaymentBrand=true）返回此 event。
| Option | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------- |
| type | string | Yes | 固定值 payment_method_selected |
| paymentMethod | string | Yes | googlepay/card |
| verificationID | string | Yes | 16位uuid |
| first6No | string | No | The first 6 digits of the card number |
| first8No | string | No | The first 8 digits of the card number |
| last4No | string | No | The last 4 digits of the card number |
| dpanFirst6No | string | No | Represents the first six digits of the DPAN.Even if the plaintext card number is available, this field must still be provided. |
| dpanFirst8No | string | No | Represents the first eight digits of the DPAN.Even if the plaintext card number is available, this field must still be provided. |
| dpanLast4No | string | No | Represents the last four digits of the DPAN.Even if the plaintext card number is available, this field must still be provided. |
| currency | string | No | 币种 |
| fundingType | string | No | Type of funding |
| issuingBank | string | No | issuerName |
| issuerCountry | string | No | issuerCountry |
| productID | string | No | |
### order_created
当用户在 Drop-in 中触发下单、订单创建成功时返回此 event
| Option | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------- |
| type | string | Yes | 固定值 order_created |
| sessionID | string | No | 同调用 Drop-in 时的 sessionID |
| merchantTransID | string | Yes | 交易订单号，可以使用 GET Payment API 查询详情 |
| econtext | object | No | 需要展示支付信息独立支付的支付方式时返 |
### payment_cancelled
当用户在 Drop-in 中主动终止支付流程退出 Drop-in 时返回此 event
| Option | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------- |
| type | string | Yes | 固定值 payment_cancelled |
| sessionID | string | Yes | 同调用 Drop-in 时的 sessionID |
### token_deleted_completed
删除Token时，若删除成功，会将结果通过event的形式，反馈给商户。
| Option | Type | Required | Description |
| ----------------- | ------ | -------- | ----------------------------- |
| type | string | Yes | 固定值 token_deleted_completed |
| sessionID | string | Yes | 同调用 Drop-in 时的 sessionID |
| cardInfo | object | Yes | |
| >cardOperationID | string | Yes | 用于唯一标识delete token操作 |
| >token | string | Yes | 删除的token |
##
#### 应答码
| 错误场景 | 应答码 | message |
| :---------------------------------- | :----- | :----------------------- |
| 字段长度格式错误 | V0000 | field {} invalid format |
| 必送字段没传 | V0001 | field {} absent or empty |
| 字段枚举值错误 | V0002 | field {} invalid value |
| Session ID 不存在 | B2001 | Session ID not found |
| Session ID 存在但是订单已经支付成功 | B2002 | Order has been paid |
| Session ID 存在但是订单已经过期 | B2003 | Order closed |
| 其他错误 | B2004 | Payment error |
## License
MIT