# Card Payment Frontend API

## 1. API
Use `PMdropin.API`.

| **API**            | **Description**          | **Details**          |
|---------------------|---------------------|---------------------|
| create | Instantiate a built-in component |  refer to [create](https://docs.payermax.com/en/202606-version/receipt/front-end-component/configuration-card.md#_1-1-create)      |
|  mount      | Mount instantiated component to `div` tag     |  refer to [mount](https://docs.payermax.com/en/202606-version/receipt/front-end-component/configuration-card.md#_1-2-mount)     |
| on           | Listen events            |  refer to [on](https://docs.payermax.com/en/202606-version/receipt/front-end-component/configuration-card.md#_1-3-on)     |
| emit            | Trigger events            |  refer to [emit](https://docs.payermax.com/en/202606-version/receipt/front-end-component/configuration-card.md#_1-4-emit)      |

### 1.1 create
Used to initialize components, please use `PMdropin.create(ComponentName, Options)`.

**ComponentName Explanation**

| **ComponentName**            | **Field Type**          | **Description**          |
|---------------------|---------------------|---------------------|
| Card | String |  Card Compoment      |

**Options Explanation**

| **Options**            | **Required Or Not**          | **Field Type**          | **Default Value**          |
|---------------------|---------------------|---------------------|---------------------|
| 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      |  `false`      |
| hideCardBrands | N |  Boolean      |  `false`      |
| hideCardHolderName | N |  Boolean      |  `false`      |
| saveCardChecked | N |  Boolean      |  `true`      |
| ignoreUserCheckedCache | N |  Boolean      |  `false`      |
| hideRecommendAccount | N |  Boolean      |  `false`      |
| openTermsInCurrentPage | N |  Boolean      |  `false`      |
| termsPopupConfig | N |  Object      |   -     |
| >>showMask | N |  Boolean      |  `true`      |
| >>closeOnClickMask | N |  Boolean      |  `true`      |

### 1.2 mount
Used to mount initialization component instances, please use `PMdropin.mount(Tag)`.

**Tag Explanation**

| **Tag**            | **Description**          |
|---------------------|---------------------|
| id | The value of the id element that needs to be mounted, such as `PMdropin.mount('#card-frame')`|
| class | The value of the class element that needs to be mounted, such as `PMdropin.mount('.card-frame')`|

### 1.3 on
Used to listen to component built-in response events, please use `PMdropin.on(Event, CallbackFunction)`.

**Event Explanation**

| **Tag**            | **Description**          | **Returned Value**          |
|---------------------|---------------------|---------------------|
| ready | Triggered when the component completes loading |`null` |
| form-check | Monitor card component verification status real-time| **refer to Event Response**|
| load | Triggered when the component completes loading | Object 
 - type：Component type card/applepay/googlepay 
- code：Response code SUCCESS indicates that the loading is successful, and the rest of the enumerations indicate that the loading failed 
- msg：response message|

Example：

```js
PMdropin.on('form-check', function(event) {
  if (event.isFormValid) {
    // Form verification passed
  }
});
```

### 1.4 emit
Used to call component built-in methods, please use `PMdropin.emit(Event, Params)`.

| **Event**            | **Params**          | **Description**          |
|---------------------|---------------------|---------------------|
| canMakePayment | - |  Get card identification      |
| switchLanguage | string |  Switch language      |
| switchTheme | string |  Switch theme      |
| addLocalization | Object |  Add customized language      |
| addTheme | Object |  Add customized theme      |
| setDisabled | Boolean |  Set component availability status      |
| setRtl | Boolean |  Set component layout from right to left      |
| setGrayscale | string |  Set component page grayscale      |

#### 1.4.1 emit.canMakePayment
Check whether the current component status meets the conditions for initiating payment, and return the card identification if the verification passes.

```js
// Example
PMdropin.emit('canMakePayment')
  .then(function(response) {
    // Verification successful
    if (response.code === 'APPLY_SUCCESS') {
      // Get paymentToken 
      var paymentToken = response.data.paymentToken
      // Go for subsequent payment operations
    }
  })
  .catch(function(error) {
    // Catching internal errors
    console.log(error);
  })
```

canMakePayment Response：

```js
// Successful API example
{
  code: 'APPLY_SUCCESS',
  data: {
    // Card indentification
    paymentToken: 'xxx'
  },
  msg: ''
}

// Failed API example
{
  code: 'FORM_INVALID',
  msg: 'Invalid params: cvv'
}
```

| **CODE码**            | **Description**          |
|---------------------|---------------------|
| APPLY_SUCCESS | Successfully obtain `paymentToken` |
| FORM_INVALID | Form validation failed |
| UNKNOWN_ISSUE | Exception information |

#### 1.4.2 emit.switchLanguage
+ Refer to [[Customization](https://docs.payermax.com/en/202606-version/receipt/front-end-component/customization.md)]

#### 1.4.3 emit.switchTheme
+ Refer to [[Customization](https://docs.payermax.com/en/202606-version/receipt/front-end-component/customization.md)]

#### 1.4.4 emit.addLocalization
+ Refer to [[Customization](https://docs.payermax.com/en/202606-version/receipt/front-end-component/customization.md)]

#### 1.4.5 emit.addTheme
+ Refer to [[Customization](https://docs.payermax.com/en/202606-version/receipt/front-end-component/customization.md)]

#### 1.4.6 emit.setDisabled
+ Set component availability status
+ Type: `Boolean`
+ Default: `false`

```js
// Uneditable status
PMdropin.emit('setDisabled', true)

// Editable status
PMdropin.emit('setDisabled', false)
```

#### 1.4.7 emit.setRtl
+ Set component layout from right to left
+ Type: `Boolean`
+ Default: `false`

```js
// Right to left Layout
PMdropin.emit('setRtl', true)

// Left to right layout
PMdropin.emit('setRtl', false)
```

#### 1.4.8 emit.setGrayscale
+ Set component page grayscale
+ Type: `String`
+ Default: `0`

```js
// Set 0 - 1 grayscale value
PMdropin.emit('setGrayscale', '1')
```