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+
• GCash
• Maya (Paymaya)
• ShopeePay
• GrabPay
• Zalopay
• VietQR

Payment Process

1. Customers visit your checkout page, enter customer shipping and billing information, and click the payment button
2. You initiate a payment request from the server to create a checkout, and you will receive the checkout ID(session_id) for loading the checkout page later
3. You use the checkout ID(session_id) and Client key(client_key) to load the embedded checkout page within the current page
4. The embedded checkout page will dynamically display supported payment methods. After the customer selects a payment method, click the payment button
5. After submitting the payment, we will process all possible additional operations, such as 3DS authentication or third-party redirect pages
6. After the payment is processed, the component callback function will be triggered, and you can handle the payment result here (the component callback function supports multiple callback events, it is recommended to at least integrate onSuccess, onExpired, onError events)
7. Your webhook address will receive the payment result notification (it is recommended that you integrate transaction query to get the payment result)

Integration Process

1. Get your transaction key
2. Get your Client key
3. Prepare your notification webhook address, provide it in the request parameters or set in the background, and notifications will be sent to the merchant at key payment nodes
4. Prepare your redirect address, provide it in the request parameters, and it will redirect after checkout payment is completed
5. Initiate the request: Create Session interface to create checkout, return checkout page URL
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)

Default component style

Create Checkout

When the customer is ready to pay, send a server-side request to create a Session and corresponding link, and initiate a payment request through the Session

Request Example Create Session

{
  "merchant_id": "18356675194960",
  "payment_type": "PURCHASE",
  "authorisation_type": "FINAL_AUTH",
  "capture_method": "AUTOMATIC",
  "trans_id": "m3246749195217",
  "expire_time": "2025-05-05T17:17:24+08:00",
  "session_mode": "DROP_IN",  # Checkout mode, HOSTED: hosted, DROP_IN: embedded, COMPONENT: component
  "display_locale": "fr-FR",
  "currency": "HKD",
  "amount": "800",
  "return_url": "https://url", 
  "payment": {
    "store_payment_method": true,  # Whether to store card information and tokenize, will get token; true: store, false: do not store
    "token_usage": "CARD_ON_FILE" 
    "shopper_reference": "854f5baaf0a735139c583c4cea14d14c" 
  },
  "goods": [
    // Product information
  ],
  "bill": {
    // Billing information
  },
  "shipping": {
    // Shipping information, required for physical goods
  },
  "customer": {
    // Consumer/customer information
  }
}

Response Example

{
    "ret_code": "000000",
    "ret_msg": "Success",
    "data": {
        "merchant_id": "18356675194960",
        "trans_id": "m3246749195217",
        "session_id": "CS208760010022288125",
        "session_mode": "DROP_IN",
        "status": "PROCESSING",
        "currency": "HKD",
        "amount": "800",
        "expire_time": "2025-05-05T17:17:24+08:00",
        "authorisation_type": "FINAL_AUTH",
        "capture_method": "AUTOMATIC"
    }
}

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

创建 PayKKaCheckout 实例时可传递参数及事件如下：

Here's a usage example:

import { PayKKaCheckout } from '@paykka/card-checkout-ui'
// 创建 PayKKaCheckout 实例
const paykkaCheckout = new PayKKaCheckout({
  sessionId: 'xxx',
  clientKey: 'xxx',
  env: 'eu',
  locale: 'en-GB',
  hidePaymentButton: false,
  threeDSFrame: {
    modalWidth: '350px',
    modalHeight: '500px',
  },
  onPaymentMethodsReady: (methods) => {
    console.log('支持的支付方式', methods)
  },
  onInitError: (error) => {
    console.log('初始化错误', error)
  },
  onSubmit: (formValidateError) => {
    console.log('提交表单全局事件', formValidateError)
  },
  onSuccess: ({ returnUrl }) => {
    console.log('支付成功全局事件', returnUrl)
  },
  onTimeout: () => {
    console.log('支付超时全局事件')
  },
  onExpired: () => {
    console.log('会话过期或失效全局事件')
  },
  onError: () => {
    console.log('支付失败全局事件')
  }
})

Creating a Drop-in Instance

Drop-in Constructor Parameters

创建 DropIn 实例时可传递参数及事件如下：

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)

Checkout Query

Query checkout status by checkout ID(session_id)

Request Example Query Session

{
  "merchant_id": "18356675194960",
  "trans_id": "m3246749195217",  # trans_id/session_id two choose one
  "session_id": "CS208760010022288125"
}

Response Example

{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "18356675194960",
    "trans_id": "m3246749195217",
    "session_id": "CS208760010022288125",
    "session_mode": "DROP_IN",
    "status": "PROCESSING",
    "amount": "800",
    "currency": "HKD",
    "expire_time": "2025-05-05T17:17:24+08:00",
    "authorisation_type": "FINAL_AUTH",
    "capture_method": "AUTOMATIC"
  }
}

Transaction Query

Query transaction status by transaction ID(order_id)

Request Example Query Transaction

{
  "merchant_id": "18356675194960",
  "trans_id": "m3246749195217",    # session_id/order_id/trans_id three choose one
  "session_id": "CS208760010022288125",
  "order_id": "GW208760010022288125"
}

Response Example

{
  "ret_code": "000000",
  "ret_msg": "Success",
  "data": {
    "merchant_id": "18356675194960",
    "trans_id": "m3246749195217",
    "order_id": "GW208760010022288125",
    "session_id": "CS208760010022288125",
    "status": "SUCCESS", # Transaction status
    "error_code": "0000", # Transaction error code
    "error_description": "request success",
    "amount": "800",
    "currency": "HKD",
    "pay_finish_time": "2025-05-05T17:17:24+08:00"
  }
}

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. The Drop-in component will receive the callback event onExpired, and you can prompt the user that the payment has expired and guide the user to initiate payment again in this event.

Error Code

See Transaction Error Code

Result Notification

Reference Webhook