# PayKKa Checkout UI Component

## How It Works

Description of image
## Preparation

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
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>
```

## Creating PayKKaCheckout Instance

Parameters and events that can be passed when creating a `PayKKaCheckout` instance:

Required parameters are marked with *.

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

 |  |
| locale | Checkout text display language.- If not provided, browser language will be used. If browser language is not supported, `en-GB` will be used by default.
- Currently supports the following 11 international languages, displayed 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 (South Korea)
  - `pt-PT`: Portuguese (Portugal)
  - `ru-RU`: Russian (Russia)
  - `zh-CN`: Chinese (China)
  - `zh-HK`: Chinese (Hong Kong)
  - `zh-TW`: Chinese (Taiwan)

 | `string` |
| hidePaymentButton | Whether to hide the payment button, defaults to `false`.- If the payment button is hidden, you need to manually call the component's `payment` method to make a payment.

 | `boolean` |
| threeDSFrame | 3DS configuration object, containing the following parameters:- `modalWidth`: 3DS popup width, defaults to adaptive if not provided. Pass `number` for units in `px`, pass `string` for custom units, minimum width is `350px`.
- `modalHeight`: 3DS popup height, defaults to adaptive if not provided. Pass `number` for units in `px`, pass `string` for custom units, minimum height is `500px`.

 | `ThreeDSFrameConfig` |
| onPaymentMethodsReady | Triggered when the checkout has obtained available payment methods.- `methods` is the list of available payment methods.
- If an empty array is returned, it means no payment methods are available, and the component will not be displayed.
- When the checkout status is success or expired, an empty array will also be returned.
- Currently supports the following 8 payment methods:
  - `APPLE_PAY`: Apple Pay
  - `GOOGLE_PAY`: Google Pay
  - `VISA`: Visa
  - `MASTER_CARD`: Master Card
  - `JCB`: JCB
  - `AMEX`: AMEX
  - `DINERS_CLUB`: Diners Club
  - `DISCOVER`: Discover

 | `(methods: PaymentMethod[]) => void` |
| onInitError | Triggered when checkout initialization fails.- `error` is a `PayKKaError` instance, typically containing the following properties:
  - `type`: Error type.
  - `message`: Error message.
  - `code`: Error code, when an API error occurs, it will return a specific [error code](#error-codes).
- This callback will also be triggered when reinitializing after checkout status is success or expired.

 | `(error: PayKKaError) => void` |
| onSubmit | **Global event** triggered when submitting the form.- `formValidateError` is the form validation error information.
- Can be overridden by the same-named event defined in the Component.

 | `(formValidateError?: Record<string, FormValidateError[]>) => void` |
| onSuccess | **Global event** triggered after successful payment.- `returnUrl` is the link to redirect to after payment is completed.
- Can be overridden by the same-named event defined in the Component.

 | `({returnUrl?: string}) => void` |
| onTimeout | **Global event** triggered when payment times out.- Users can resubmit the form to make a payment.
- Can be overridden by the same-named event defined in the Component.

 | `() => void` |
| onExpired | **Global event** triggered when the session expires or becomes invalid, or when the component is called again after successful payment.- Can be overridden by the same-named event defined in the Component.

 | `() => void` |
| onError | **Global event** triggered after payment failure.- `error` is a `PayKKaError` instance, typically containing the following properties:
  - `type`: Error type.
  - `message`: Error message.
  - `code`: Error code, when an API error occurs, it will return a specific [error code](#error-codes).
- Users can resubmit the form to make a payment.
- Can be overridden by the same-named event defined in the Component.

 | `(error: PayKKaError) => void` |


Here's an example of usage:

npm

```javascript
import { PayKKaCheckout } from '@paykka/card-checkout-ui'
// Create PayKKaCheckout instance
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'eu',
  locale: 'en-GB',
  hidePaymentButton: false,
  threeDSFrame: {
    modalWidth: '350px',
    modalHeight: '500px',
  },
  onPaymentMethodsReady: (methods) => {
    console.log('Supported payment methods', methods)
  },
  onInitError: (error) => {
    console.log('Initialization error', error)
  },
  onSubmit: (formValidateError) => {
    console.log('Form submission global event', formValidateError)
  },
  onSuccess: ({ returnUrl }) => {
    console.log('Payment success global event', returnUrl)
  },
  onTimeout: () => {
    console.log('Payment timeout global event')
  },
  onExpired: () => {
    console.log('Session expired or invalid global event')
  },
  onError: () => {
    console.log('Payment failure global event')
  }
})
```

CDN

```javascript
const { PayKKaCheckout } = PayKKaCardCheckoutUI
// Create PayKKaCheckout instance
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'eu',
  locale: 'en-GB',
  hidePaymentButton: false,
  threeDSFrame: {
    modalWidth: '350px',
    modalHeight: '500px',
  },
  onPaymentMethodsReady: (methods) => {
    console.log('Supported payment methods', methods)
  },
  onInitError: (error) => {
    console.log('Initialization error', error)
  },
  onSubmit: (formValidateError) => {
    console.log('Form submission global event', formValidateError)
  },
  onSuccess: ({ returnUrl }) => {
    console.log('Payment success global event', returnUrl)
  },
  onTimeout: () => {
    console.log('Payment timeout global event')
  },
  onExpired: () => {
    console.log('Session expired or invalid global event')
  },
  onError: () => {
    console.log('Payment failure global event')
  }
})
```

### Detailed Explanation

#### 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, you can set `hidePaymentButton` to `true` to hide PayKKa's payment button. After users click your payment button, you can call the `payment` method exposed by the component instance to process the payment.

Here's an example using the Card component:

npm

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


```javascript javascript
// Assuming we have initialized the checkout and set hidePaymentButton to true
import { Card } from '@paykka/card-checkout-ui'

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

const handleClickPayment = () => {
  // After clicking the payment button, call the payment method to process payment
  CheckoutCard.ref.payment()
}
```

CDN

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


```javascript javascript
// Assuming we have initialized the checkout and set hidePaymentButton to true
const { Card } = PayKKaCardCheckoutUI

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

const handleClickPayment = () => {
  // After clicking the payment button, call the payment method to process payment
  CheckoutCard.ref.payment()
}
```

#### Fraud Detection

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

#### Error Codes

See [Transaction Error Codes](/payments/docs/developer-resources/transanction-error-code)

## Creating Component Instance

After creating the checkout instance, you can create components. For example, let's say we need to import the Card component:

### Step 1: Create DOM Element

Create a DOM element in your checkout page that will be used to render the Component.


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

It is strongly recommended not to create this DOM element inside an iframe element, as it may prevent the checkout from functioning properly.

### Step 2: Import Component and Build Instance


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

// Steps to create PayKKaCheckout instance omitted here

const checkoutCard = paykkaCheckout.create(Card, {
  // Parameters required for Card component
})
```

### Step 3: Mount Component


```javascript
const container = document.querySelector('#card-container')
checkoutCard.mount(container)
```

If you are using JavaScript frameworks like Angular, Vue, React, etc., please ensure that the DOM has been rendered before mounting, and do not re-render the element.

## Using Sandbox Environment

If you want to integrate the checkout in a sandbox environment, follow these steps.

1. If using CDN import, you need to use the sandbox environment link (for npm method, proceed to the next step):



```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>
```

1. When creating the checkout, set `env` to `sandbox`:



```js
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'sandbox' // [!code highlight]
  // ...other options
})
```