Drop-in Web

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Introduction

The embedded checkout supports embedding PayKKa's checkout payment component into your checkout page to collect consumer payment information.

You can create your own checkout flow through the PayKKa Checkout UI component. The payment information entered by consumers is only transmitted within the component, which can reduce your PCI-DSS compliance costs.

Supported Payment Methods

• Visa
• MasterCard
• JCB
• American Express
• Discover
• Diners Club
• Apple Pay
• Google Pay
• WechatPay
• Alipay+

Payment Process

1. Get your transaction key
2. Get your Client key
3. Prepare your notification webhook address, provide it in the request parameters, and notifications will be sent to the merchant at key payment nodes
4. Prepare your redirect webhook address, provide it in the request parameters, and it will redirect after checkout payment is completed
5. Initiate the request
6. For frontend component integration method, see PayKKa Checkout UI Component
7. Merchants can integrate the Query Session interface to get checkout results, or directly integrate the Query Transaction interface to get order results (if there is no final result, it means the consumer did not initiate a transaction)

API: Create Session

Default component style

Adding Drop-in

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

npm i @paykka/card-checkout-ui

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

Creating a PayKKaCheckout Instance

PayKKaCheckout Constructor Parameters

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

Here's a usage example:

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')
  }
})

Creating a Drop-in Instance

Drop-in Constructor Parameters

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

Step 1: Create DOM Element

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

<div id="drop-in-container"></div>

Step 2: Import DropIn and Create Instance

import { PayKKaCheckout, DropIn } from '@paykka/card-checkout-ui'

// Steps to create PayKKaCheckout instance omitted here

const checkoutDropIn = paykkaCheckout.create(DropIn, {
  paymentMethods: {
    card: {
      /** Card component constructor parameters */
    },
    applePay: {
      /** ApplePay component constructor parameters */
    },
    googlePay: {
      /** GooglePay component constructor parameters */
    }
  },
  layout: 'tabs',
  onSubmit: formValidateError => {
    console.log('Form submission event', formValidateError)
  },
  onSuccess: ({ returnUrl }) => {
    console.log('Payment success event', returnUrl)
  },
  onTimeout: () => {
    console.log('Payment timeout event')
  },
  onExpired: () => {
    console.log('Session expired or invalid event')
  },
  onError: () => {
    console.log('Payment failure event')
  }
})

Step 3: Mount Component

const container = document.querySelector('#drop-in-container')
checkoutDropIn.mount(container)

Purchase and Recurring

If your payment requirements involve recurring charges from customers' bank cards or e-wallets at regular intervals (such as monthly, yearly, or custom time intervals) without requiring manual authorization each time, you can use PayKKa's recurring payment feature.

Integration Method

1. Currently, PayKKa's recurring payment feature requires the merchant to initiate it periodically
2. For the first recurring payment, PayKKa needs to store the card information of the cardholder, and subsequent recurring payments only need to provide the cardholder's token
3. For subsequent recurring payments, only the cardholder's token needs to be provided, without repeating card information

First recurring request example Create Session

{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "COMPONENT",
  "display_locale": "fr-FR",
  "currency": "HKD",
  "amount": "800",
  "return_url": "https://url",
  "mit": false,
  "payment": {
    "store_payment_method": true,
    "token_usage": "SUBSCRIPTION",
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c"
  },
  "goods": [
    // Product information
  ],
  "bill": {
    // Billing information
  },
  "shipping": {
    // Shipping information, required for physical goods
  },
  "customer": {
    // Consumer/customer information
  }
}

Subsequent recurring request example Initiate Transaction

{
  "merchant_id": "18356675194960",
  "payment_type": "RECURRING",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "currency": "HKD",
  "amount": "800",
  "mit": true,
  "recurring_agreement_id": "RA4264524535435435",
  "payment": {
    "payment_method": "BANKCARD",
    "shopper_reference": "558b5cb1b8cbcc8496062155c69cf2ab",
    "token": "TK20231435132143229"
  }
}

3DS Processing

The checkout product does not require you to handle 3DS authentication. PayKKa will automatically perform intelligent security detection and processing of payments. You only need to focus on the payment results.

Validity Period

The maximum validity period for the checkout is 24 hours. After expiration, payment cannot be continued.

Error Code

See Transaction Error Code

Result Notification

Reference Webhook