# PayKKa Checkout UI Component

## How It Works

Description of image
## Before You Start

You can install the PayKKa Checkout UI npm package, or embed it into HTML via CDN:

npm (Recommended)
Install `@paykka/card-checkout-ui`:

npm
```bash
npm i @paykka/card-checkout-ui
```

pnpm
```bash
pnpm i @paykka/card-checkout-ui
```

yarn
```bash
yarn add @paykka/card-checkout-ui
```

To properly display the component, you need to import the styles globally:

```typescript
import '@paykka/card-checkout-ui/style.css'
```

CDN
Import PayKKa Checkout UI styles and scripts in HTML via CDN links. It is recommended to use the CDN link for the corresponding region:

Europe
```html
<link href="https://checkout.eu.paykka.com/cp/style.css" rel="stylesheet" />
<script src="https://checkout.eu.paykka.com/cp/card-checkout-ui.js"></script>
```

Hong Kong
```html
<link href="https://checkout.aq.paykka.com/cp/style.css" rel="stylesheet" />
<script src="https://checkout.aq.paykka.com/cp/card-checkout-ui.js"></script>
```

Sandbox
```html
<link href="https://checkout-sandbox.aq.paykka.com/cp/style.css" rel="stylesheet"/>
<script src="https://checkout-sandbox.aq.paykka.com/cp/card-checkout-ui.js"></script>
```

## Initialization

Before you can use the component, you need to initialize a PayKKa checkout instance:

npm
```javascript
import { PayKKaCheckout } from '@paykka/card-checkout-ui'

// Create the checkout instance
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'xx',
  // ...other configuration
})

// Wait for the checkout to finish initialization before loading components
paykkaCheckout.init().then(() => {
  // ...load components
})
```

CDN
```javascript
// PayKKaCardCheckoutUI is the checkout object mounted on window
const { PayKKaCheckout } = PayKKaCardCheckoutUI

// Create the checkout instance
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'xx',
  // ...other configuration
})

// Wait for the checkout to finish initialization before loading components
paykkaCheckout.init().then(() => {
  // ...load components
})
```

We strongly recommend that you do not create the checkout inside an `iframe`, otherwise it may not function properly.

### Initialization Options

You can currently configure the following options when creating the checkout instance:

Required fields are marked with *

| Name  | Description  | Type  | Default Value  |
|  --- | --- | --- | --- |
| *sessionId | Checkout ID used to create the checkout | `string` | `undefined` |
| *clientKey | Client key | `string` | `undefined` |
| *env | Environment configuration- `eu` for European merchants
- `hk` for Hong Kong merchants
- `sandbox` for sandbox merchants

 | `eu | hk | sandbox` | `undefined` |
| locale | Display language used by the checkout- If not provided, the browser language is used. If the browser language is not in the [supported language list](#language), `en-GB` is used by default.

 | `string` | Browser language | `en-GB` |
| hidePaymentButton | Whether to hide the payment button- If the payment button is hidden, you need to manually call the component's `payment` method to complete the payment. See [Custom Payment Button](#custom-payment-button) for usage.

 | `boolean` | `false` |
| onPaymentMethodsReady | Called when the checkout has loaded [available payment methods](#payment-methods), and returns those methods- If an empty array is returned, it means no payment methods are available and the component will not be displayed.
- An empty array is also returned when the checkout status is successful or expired.

 | `(methods: PaymentMethod[]) => void` | `undefined` |
| onInitError | Triggered when an error occurs during checkout initialization- `error` is the [error information](#error-information)
- This callback is also triggered if initialization is attempted again after the checkout status becomes successful or expired.

 | `(error: PayKKaError) => void` | `undefined` |
| threeDSFrame | Defines the [3DS configuration](#3ds-configuration) | `ThreeDSFrameConfig` | `undefined` |


Below are more details about some of these options:

### Custom Payment Button

`hidePaymentButton` is used to configure whether to hide PayKKa's built-in payment button.

If you want to use your own payment button, set `hidePaymentButton` to `true` to hide PayKKa's payment button. After the user clicks your payment button, you can call the `payment` method exposed by the component instance to proceed with the payment.

Here is an example using the Card component:

npm
```html html
<button onclick="handleClickPayment()">Pay</button>
```

```javascript javascript
// Assume the checkout has already been initialized and hidePaymentButton is set to true
import { Card } from '@paykka/card-checkout-ui'

// Create the Card component
const CheckoutCard = paykkaCheckout.create(Card, {
  // card configuration
})

const handleClickPayment = () => {
  // Call the payment method after the user clicks the payment button
  CheckoutCard.ref.payment()
}
```

CDN
```html html
<button onclick="handleClickPayment()">Pay</button>
```

```javascript javascript
// Assume the checkout has already been initialized and hidePaymentButton is set to true
const { Card } = PayKKaCardCheckoutUI

// Create the Card component
const CheckoutCard = paykkaCheckout.create(Card, {
  // card configuration
})

const handleClickPayment = () => {
  // Call the payment method after the user clicks the payment button
  CheckoutCard.ref.payment()
}
```

### Language

PayKKa Checkout UI currently supports the following 11 locales, shown in IETF BCP 47 format:

- `de-DE`: German (Germany)
- `en-GB`: English (United Kingdom)
- `es-ES`: Spanish (Spain)
- `fr-FR`: French (France)
- `ja-JP`: Japanese (Japan)
- `ko-KR`: Korean (Korea)
- `pt-PT`: Portuguese (Portugal)
- `ru-RU`: Russian (Russia)
- `zh-CN`: Chinese (China)
- `zh-HK`: Chinese (Hong Kong)
- `zh-TW`: Chinese (Taiwan)


By default, when creating the checkout, we use the language from the retrieved checkout information. If that language is not supported, the browser language is used. If that is still not supported, `en-GB` is used. If you want to force a specific language, you can configure `locale` when creating the checkout.

### Payment Methods

PayKKa Checkout UI currently supports the following 8 payment methods:

- `APPLE_PAY`: Apple Pay
- `GOOGLE_PAY`: Google Pay
- `VISA`: Visa
- `MASTER_CARD`: MasterCard
- `JCB`: JCB
- `AMEX`: AMEX
- `DINERS_CLUB`: Diners Club
- `DISCOVER`: Discover


### 3DS Configuration

You can define some 3DS settings during initialization. The current configuration items are:

```typescript
interface ThreeDSFrameConfig {
  /** Width of the 3DS modal. If not provided, it adapts automatically. If a number is passed, the unit is px. If a string is passed, you can use a custom unit. The minimum width is 350px. */
  modalWidth?: number | string
  /** Height of the 3DS modal. If not provided, it adapts automatically. If a number is passed, the unit is px. If a string is passed, you can use a custom unit. The minimum height is 500px. */
  modalHeight?: number | string
}
```

### Fraud Detection

For fraud detection (`FraudDetection`) configuration, please refer to [Fraud Detection SDK](/payments/docs/fraud/fraud-detection).

### Error Information

All checkout errors are thrown as `PayKKaError` instances, which usually include the following properties:

- `type`: Error type
- `message`: Error message
- `code`: Error code. When an API error occurs, the specific [error code](/payments/docs/developer-resources/transaction-error-code) is returned.


## How to Use Components

After creating the checkout instance, you can create components. For example, if you need to use the Card component:

npm
```javascript
import { Card } from '@paykka/card-checkout-ui'
```

CDN
```javascript
const { Card } = PayKKaCardCheckoutUI
```

Call the `create` method on the checkout instance and pass in the required component `props` to create a component instance:

```typescript
const props = {
  // card props
}

// Call the create method on the checkout instance
const InstCard = paykkaCheckout.create(Card, props)
```

The component instance provides a `mount` method, which accepts either an `HTMLElement` object or a CSS selector string and renders the component into the real DOM:

```html
<div id="card"></div>
```

```typescript
// Pass in an HTMLElement
const container = document.querySelector('#card')
InstCard.mount(container)

// or

// Pass in a CSS selector string
InstCard.mount('#card')
```

At this point, the component has been successfully rendered on the page.

## Using the Sandbox Environment

If you want to integrate the checkout in the sandbox environment, here is an example using CDN:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>PayKKa Checkout Sandbox Example</title>
    <!-- Import the stylesheet and script for the sandbox environment -->
    <link href="https://checkout-sandbox.aq.paykka.com/cp/style.css" rel="stylesheet"/>
    <script src="https://checkout-sandbox.aq.paykka.com/cp/card-checkout-ui.js"></script>
  </head>
  <body>
    <div id="card"></div>

    <script>
      const { PayKKaCheckout, Card } = PayKKaCardCheckoutUI

      // Create the checkout instance
      const paykkaCheckout = new PayKKaCheckout({
        sessionId: 'xxx',
        clientKey: 'xxx',
        // Set the environment to sandbox
        env: 'sandbox',
        // ...other configuration
      })

      // Wait for the checkout to finish initialization
      paykkaCheckout.init().then(() => {
        // Create a component, using Card as an example
        const InstCard = paykkaCheckout.create(Card, {})
        const container = document.querySelector('#card')
        // Mount the component
        InstCard.mount(container)
      })
    </script>
  </body>
</html>
```