> ## Documentation Index
> Fetch the complete documentation index at: https://doc.haipay.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Integration Modes

> Compare HaiPay Checkout Mode (payUrl redirect) and Component Mode (clientToken JS embed), understand how payment methods decouple from checkout UI integration, and choose the right path for your checkout.

In HaiPay's payment architecture, **Payment Methods** (what the customer pays with—such as cards, Apple Pay, Google Pay, or local e-wallets) and **Checkout Integration Modes** (how the checkout UI is presented to the customer) are decoupled:

* Whether you are building a one-time payment, an MIT (Merchant-Initiated Transaction) authorization, or a recurring subscription, your server calls the corresponding create endpoint.
* The API response returns both `payUrl` and `clientToken`—you simply choose whether to redirect the customer to HaiPay's hosted checkout via `payUrl` (**Checkout Mode**) or mount the embedded component on your own page via `clientToken` (**Component Mode**).

> [card] [Checkout Mode](https://doc.haipay.net/en/payments/payment-link.md)
>
> Deploy in checkout mode for quick verification. Use the returned `payUrl` to redirect users to a HaiPay-hosted payment page with almost zero frontend code.

> [card] [Component Mode](https://doc.haipay.net/en/payments/frontend-payment-element.md)
>
> Deploy in component mode for optimal build efficiency. Use the returned `clientToken` to mount a pre-built payment UI directly inside your page.

![Comparison between Component Mode (deploy in component mode for optimal build efficiency) and Checkout Mode (deploy in checkout mode for quick verification)](https://mintcdn.com/haipay-3385f6e8/ODUYliyREFGls8kZ/images/en/guide/integration-modes-comparison.png?fit=max\&auto=format\&n=ODUYliyREFGls8kZ\&q=85\&s=4e66d32d8365ca98b813db90b117d3da)

Visual and architectural comparison between Component Mode and Checkout Mode

## Comparison & Selection Matrix

Following industry standards for checkout experience and PCI compliance scope, here is how the two integration modes compare:

| Dimension | Checkout Mode (`payUrl` Redirect) | Component Mode (`clientToken` Embed) |
| :- | :- | :- |
| **Checkout Experience** | Redirects shoppers from your site or app to a secure, pre-built checkout page hosted by HaiPay, then returns to `callBackUrl` | Renders the payment Component directly inside your page's DOM container so shoppers complete payment without leaving your site |
| **Frontend Effort** | Minimal A single redirect line (`window.location.href = payUrl`) | Moderate Load the JS SDK, mount the container, and listen to `ready` / `paymentStatus` events |
| **UI Customization** | Standard hosted layout; supports passing `cancelUrl` to display a return button | Configurable theme (`light` / `dark`), card form placement (`top` / `bottom`), submit button visibility, and wallet button labels |
| **PCI DSS Scope** | Minimal burden (SAQ A equivalent) (Sensitive cardholder data is handled entirely on HaiPay's hosted page and never touches your servers or frontend) | No merchant PCI DSS certification required (hosted by Component) (Card numbers, CVV, and other sensitive fields are collected and isolated by HaiPay's Component; no merchant PCI DSS certification required) |
| **Key Response Field** | `data.payUrl` | `data.clientToken` |
| **Supported Transaction Types** | One-time collection (CIT), initial MIT authorization, initial subscription authorization | One-time collection & initial MIT authorization (`mode: 'payment'`), initial subscription authorization (`mode: 'subscription'`) |
| **Supported Payment Methods** | Cards (credit & debit cards), Apple Pay, Google Pay, and regional local payment methods worldwide | Currently supports cards (credit & debit cards), Apple Pay, and Google Pay; **expanding to regional local e-wallets and local payment methods** |

> [!TIP]
>
> HaiPay Component Mode is designed as an extensible payment container. Beyond cards (supporting both credit and debit cards across VISA / MasterCard / JCB / AMEX / Diners / Discover), Apple Pay, and Google Pay, **regional e-wallets and local payment methods will progressively become available in Component Mode**. Once enabled on your merchant account, new methods can be rendered without rebuilding your checkout frontend.

## Dynamically Controlling Displayed Methods & Order (`paymentMethods` vs. `inBankCode`)

When calling Card Collection (`/usd/collect/apply`), MIT Apply (`/usd/mit/apply`), or Subscription Apply (`/subscription/apply`), you can control whether a single payment method or a dynamically ordered list is presented:

| Parameter Usage | When to Use | Behavior |
| :- | :- | :- |
| **Pass `inBankCode` only** (omit `paymentMethods`) | Specify a single payment method (e.g., when the shopper already selected a method on your page) | Launches or renders only that specific payment method (`CREDIT_CARD`, `GOOGLE_PAY`, or `APPLE_PAY`). |
| **Pass `paymentMethods` only** (omit `inBankCode`) | Display multiple payment methods and **dynamically control which methods appear and their top-to-bottom order** | Pass a comma-separated list of payment method codes. The checkout **displays only the specified methods and arranges them strictly from top to bottom in the order passed**. For example, passing `"GOOGLE_PAY,CREDIT_CARD"` renders only Google Pay and Cards, with Google Pay on top and Cards below. |

> [!NOTE]
>
> **Important Rules**:
>
> 1. `inBankCode` and `paymentMethods` are **mutually exclusive**: when `inBankCode` is omitted, `paymentMethods` is required, and vice versa.
> 2. Dynamic filtering and top-to-bottom ordering via `paymentMethods` also applies to the [Global Cashier (`/global/cashier/collect/apply`)](https://doc.haipay.net/en/payments/global-cashier).

## How to Choose?

> [tab] When to Choose Checkout Mode
>
> * **Quick verification & fastest launch**: Launch a complete payment flow in hours with virtually zero frontend work.
> * **Link-based or cross-channel scenarios**: Ideal for mobile H5, email invoices, chat links, or lightweight apps.
> * **Zero UI maintenance**: Let HaiPay handle responsive layout, browser compatibility, and security isolation.
>
> 👉 Read the [Checkout Mode Guide](https://doc.haipay.net/en/payments/payment-link.md)

> [tab] When to Choose Component Mode
>
> * **Optimal build efficiency & brand continuity**: Keep users on your domain throughout checkout without full-page redirects.
> * **Unified custom checkout**: Display Apple Pay, Google Pay, and card inputs in a single container, or trigger card submission from your own checkout button.
> * **One component for multiple scenarios**: Support both standard collection / MIT payments (`mode: 'payment'`) and fixed-term recurring subscriptions (`mode: 'subscription'`) with the same Component integration.
>
> 👉 Read the [Component Mode Guide](https://doc.haipay.net/en/payments/frontend-payment-element.md)

## Related Topics

* [Checkout Mode](https://doc.haipay.net/en/payments/payment-link.md)
* [Component Mode](https://doc.haipay.net/en/payments/frontend-payment-element.md)
* [Card Payments Overview](https://doc.haipay.net/en/payments/card.md)
* [CIT vs. MIT Transaction Modes](https://doc.haipay.net/en/payments/cit-mit.md)
* [Global Cashier](https://doc.haipay.net/en/payments/global-cashier.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.