# ApplePay Frontend API

## 1. Preparations

ApplePay certificates are uniformly maintained by PayerMax, merchants only need to download the ApplePay certification file and save it in the specified location.

1. Contact PayerMax technical support to provide the domain names of your official and test environments to complete Apple's domain name certification requirements. Especially note that `127.0.0.1`, `LAN IP`, `localhost` can't pull up ApplePay in the test environment.

2. Download the ApplePay authentication file and place it in the specified path `https://[Pending Domain Name Registration]/.well-known/apple-developer-merchantid-domain-association`.

  - Test environment certification documentation: [apple-developer-merchantid-domain-association](https://img-cdn-sg.payermax.com/public/20250703-93d02b05-fc2a-4569-b8a0-65887e5453a6apple-developer-merchantid-domain-association)；

  - Documentation of certification of the production environment: [apple-developer-merchantid-domain-association](https://img-cdn-sg.payermax.com/public/20250730-0a4ca772-d0fa-49c3-82d1-ced08252b290apple-developer-merchantid-domain-association).

3. After the merchant has configured the certificate, notify PayerMax to validate the domain certificate and PayerMax will operate the domain certificate validation in the Apple developer backend. If the validation fails, the possible reasons are as follows:

  - The certificate path is misconfigured;

  - Your firewall is blocking the Apple Check service, please configure the [link page](https://developer.apple.com/documentation/applepayontheweb/setting-up-your-server) domain to the server whitelist;

  - You may have already configured a certificate for another MerchantID. In this case, you can use the new domain name, or delete the corresponding domain certificate on the original developer account.

## 2. API

Use `PMdropin.API`.

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

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

**ComponentName Explanation**

| **ComponentName**            | **Field Type**          | **Description**          |
|---------------------|---------------------|---------------------|
| applepay | string |  ApplePay Compoment      |

**Options Explanation**

| **Options**            | **Required Or Not**          | **Field Type**          | **Default Value**          | 
|---------------------|---------------------|---------------------|---------------------|
| clientKey | Y |  String      |  -      |
| sessionKey | Y |  String      |  -      |
| sandbox | N |  Boolean      |  `false`      |
| theme | N |  String      | `light`      |
| payButtonStyle | N |  String      |  -      |

### 2.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('#applepay-frame')`|
| class | The value of the class element that needs to be mounted, such as `PMdropin.mount('.applepay-frame')`|

### 2.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` |
| payButtonClick | Triggered when the ApplePay button is clicked| `null`|

Example:

```js [payButtonClick]
PMdropin.on('payButtonClick', function(event) {
  // Obtain paymentToken and call orderAndPay API
  applePay.emit('setDisabled', true)
  applePay.emit('canMakePayment')
    .then(res => {
      const paymentToken = res?.data?.paymentToken 
      if(paymentToken){
       _postapi('orderAndPay',params).then(res =>{
                    const code = (res || {}).code
                    if (code == 'APPLY_SUCCESS') {    
                      // After the server receives the payment success callback, 
                      // it needs to return the result to the front end. 
                      // The front end calls applepay.emit('paySuccess'), 
                      // the ApplePay pop-up will close and prompt "Payment Successful".
                      applepay.emit('paySuccess')
                    } else {
                      applepay.emit('payFail')
                    }
      })}else{ 
        applePay.emit('setDisabled', false)
      }
    })
    .catch(err => {
      applePay.emit('payFail')
      applePay.emit('setDisabled', false) 
    })
    
});
```

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

| **Event**            | **Params**          | **Description**          |
|---------------------|---------------------|---------------------|
| canMakePayment | - |  Get the payment token      |
| switchTheme | string |  Switch theme      |
| setDisabled | Boolean |  Set the component available state      |
| setpayButtonStyle | string |  Set the button style      |

#### 2.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.

Options configuration:

| **Options**            | **Required Or No**          | **Field Type**          | **Description**          | **Default Value**          |
|---------------------|---------------------|---------------------|---------------------|---------------------|
| totalAmount | N |  String      |  The Apple Pay payment page displays the amount as a numeric string, with a maximum of two decimal places.
Passing an invalid value will cause the `canMakePayment` response to throw an `AMOUNT_INVALID` exception.
Note: This only applies when `applyDropinSession` does not specify an amount. If `applyDropinSession` includes an amount, do not use this feature. Ensure that the `totalAmount` passed to `canMakePayment` matches the final payment amount passed to `orderAndPay`.      |  -      |

canMakePayment Response：

| **Code**            | **Description**          | 
|---------------------|---------------------|
| APPLY_SUCCESS | Get `paymentToken` successfully |  
| UNKNOWN_ISSUE | Exception information | 
| AMOUNT_INVALID | The input amount format is incorrect | 
| APPLEPAY_INTERNAL_ERROR | Apple Pay internal error | 

#### 2.4.2 emit.switchTheme
+ Set the button theme
+ Type: `Boolean`
+ Default: `light`

| **Theme Name**            | **Theme type**          | **Effect Preview**          |
|---------------------|---------------------|---------------------|
| White | light `默认` |  ![](https://img-cdn-sg.payermax.com/public/20240801-ac3e16a0-6aca-4333-8f2b-431df925b8ee.png)      |
| Black | dark |  ![](https://img-cdn-sg.payermax.com/public/20240801-91bfb336-b33d-484d-a142-2ec5a3d8007d.png)      |

#### 2.4.3 emit.setDisabled
+ Set the component available state
+ Type: `Boolean`
+ Default: `false`

```js
// Button disabled state
PMdropin.emit('setDisabled', true)

// Button enabled state
PMdropin.emit('setDisabled', false)
```

#### 1.4.4 emit.setpayButtonStyle
+ Set the button style
+ Type: `Boolean`
+ Default: `false`

```js
// Set the width, height, padding, and border radius of the ApplePay button
PMdropin.emit('payButtonStyle', `width:20rem;height:4rem;border-radius: 4rem;padding:1rem 4rem;`)
```