# 卡支付前端接口

## 1. API
使用方法 `PMdropin.API`。

| **API**            | **描述**          | **详情**          |
|---------------------|---------------------|---------------------|
| create | 实例化一个内置组件 |  参阅[create](https://docs.payermax.com/202606-version/receipt/front-end-component/configuration-card.md#_1-1-create)      |
|  mount      | 将实例化组件挂载到`div`标签      |  参阅[mount](https://docs.payermax.com/202606-version/receipt/front-end-component/configuration-card.md#_1-2-mount)     |
| on           | 监听事件            |  参阅[on](https://docs.payermax.com/202606-version/receipt/front-end-component/configuration-card.md#_1-3-on)     |
| emit            | 触发事件            |  参阅[emit](https://docs.payermax.com/202606-version/receipt/front-end-component/configuration-card.md#_1-4-emit)      |

### 1.1 create
用于初始化组件，使用方法 `PMdropin.create(ComponentName, Options)`。

**ComponentName详解**

| **ComponentName**            | **字段类型**          | **描述**          |
|---------------------|---------------------|---------------------|
| card | string |  卡组件      |

**Options详解**

| **Options**            | **是否必填**          | **字段类型**          | **描述**          | **默认值**          |
|---------------------|---------------------|---------------------|---------------------|---------------------|
| clientKey | Y |  String      |  客户端公钥      |  -      |
| sessionKey | Y |  String      |  安全访问令牌      |  -      |
| sandbox | N |  Boolean      |  沙盒环境      |  `false`      |
| language | N |  String      |  语言      |  `en`      |
| theme | N |  String      |  主题      |  `light`      |
| customLocalization | N |  Object      |  自定义语言	      |  -      |
| customTheme | N |  Object      |  自定义主题	      |  -      |
| grayscale | N |  String      |  页面灰度      |  `'0'`      |
| isRtl | N |  Boolean      |  从右到左	      |  `false`      |
| hideSaveCard | N |  Boolean      |  隐藏Save保存	      |  `false`      |
| hideCardBrands | N |  Boolean      |  隐藏头部卡组织LOGO	      |  `false`      |
| hideCardHolderName | N |  Boolean      |  隐藏卡姓名	      |  `false`      |
| saveCardChecked | N |  Boolean      |  保存卡信息的checkbox是否选中
true - 勾选
false - 不勾选
注：当hideSaveCard = false时，该字段生效	      |  `true`      |
| ignoreUserCheckedCache | N |  Boolean      |  是否忽略用户勾选缓存
false - 默认不忽略
true - 忽略
注：当hideSaveCard = false时，该字段生效	      |  `false`      |
| hideRecommendAccount | N |  Boolean      |  是否隐藏推荐卡模块
	      |  `false`      |
| openTermsInCurrentPage | N |  Boolean      |  是否在当前页面打开协议弹框
	      |  `false`      |
| termsPopupConfig | N |  Object      |  协议弹框配置
注：当openTermsInCurrentPage = true时，该字段生效
	      |    -    |
| >>showMask | N |  Boolean      |  是否展示遮罩层
	      |  `true`      |
| >>closeOnClickMask | N |  Boolean      |  点击遮罩是否关闭弹框
	      |  `true`      |

### 1.2 mount
用于挂载初始化组件实例，使用方法`PMdropin.mount(Tag)`。

**Tag详解**

| **Tag**            | **描述**          |
|---------------------|---------------------|
| id | 需要挂载的id元素值，如 `PMdropin.mount('#card-frame')`|
| class | 需要挂载的class元素值，如 `PMdropin.mount('.card-frame')`|

### 1.3 on
用于监听组件内置响应事件，使用方法`PMdropin.on(Event, CallbackFunction)`。

**Event详解**

| **Tag**            | **描述**          | **返回值**          |
|---------------------|---------------------|---------------------|
| ready | 组件加载完成时触发 |`null` |
| form-check | 实时监听卡组件校验状态| **参阅下方 Event Response**|
| load | 组件加载完成时触发| Object 
 - type：组件类型card/applepay/googlepay 
- code：响应码 SUCCESS 表示加载成功，其余枚举表示加载失败
- msg：响应 message|

示例：

```js
PMdropin.on('form-check', function(event) {
  if (event.isFormValid) {
    // 表单校验通过
  }
});
```

### 1.4 emit
用于调用组件内置方法，使用方法`PMdropin.emit(Event, Params)`。

| **Event**            | **Params**          | **描述**          |
|---------------------|---------------------|---------------------|
| canMakePayment | - |  获取卡标识      |
| switchLanguage | string |  切换语言      |
| switchTheme | string |  切换主题      |
| addLocalization | Object |  添加自定义语言      |
| addTheme | Object |  添加自定义主题      |
| setDisabled | Boolean |  设置组件可用状态      |
| setRtl | Boolean |  设置组件从右到左布局      |
| setGrayscale | string |  设置组件页面灰度      |

#### 1.4.1 emit.canMakePayment
检查当前组件状态是否具备发起支付条件，如果校验通过则返回卡标识。

```js
// 示例
PMdropin.emit('canMakePayment')
  .then(function(response) {
    // 验证成功
    if (response.code === 'APPLY_SUCCESS') {
      // 获取 paymentToken 
      var paymentToken = response.data.paymentToken
      // 进行后续支付操作
    }
  })
  .catch(function(error) {
    // 捕获内部异常错误
    console.log(error);
  })
```

canMakePayment Response：

```js
// 接口成功示例
{
  code: 'APPLY_SUCCESS',
  data: {
    // 卡标识
    paymentToken: 'xxx'
  },
  msg: ''
}

// 接口失败示例
{
  code: 'FORM_INVALID',
  msg: 'Invalid params: cvv'
}
```

| **CODE码**            | **描述**          |
|---------------------|---------------------|
| APPLY_SUCCESS | 成功获取 `paymentToken` |
| FORM_INVALID | 表单校验失败 |
| UNKNOWN_ISSUE | 异常信息 |

#### 1.4.2 emit.switchLanguage
+ 参阅【[定制化](https://docs.payermax.com/202606-version/receipt/front-end-component/customization.md)】

#### 1.4.3 emit.switchTheme
+ 参阅【[定制化](https://docs.payermax.com/202606-version/receipt/front-end-component/customization.md)】

#### 1.4.4 emit.addLocalization
+ 参阅【[定制化](https://docs.payermax.com/202606-version/receipt/front-end-component/customization.md)】

#### 1.4.5 emit.addTheme
+ 参阅【[定制化](https://docs.payermax.com/202606-version/receipt/front-end-component/customization.md)】

#### 1.4.6 emit.setDisabled
+ 设置组件可用状态
+ 类型 `Boolean`
+ 默认：`false`

```js
// 不可编辑状态
PMdropin.emit('setDisabled', true)

// 可编辑状态
PMdropin.emit('setDisabled', false)
```

#### 1.4.7 emit.setRtl
+ 设置组件从右到左布局
+ 类型： `Boolean`
+ 默认：`false`

```js
// 从右到左布局
PMdropin.emit('setRtl', true)

// 从左到右布局
PMdropin.emit('setRtl', false)
```

#### 1.4.8 emit.setGrayscale
+ 设置组件页面灰度
+ 类型： `String`
+ 默认：`0`

```js
// 设置 0 - 1 灰度值
PMdropin.emit('setGrayscale', '1')
```