Checkout Integration Modes

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).

Checkout Mode

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.

Component Mode

Deploy in component mode for optimal build efficiency. Use the returned clientToken to mount a pre-built payment UI directly inside your page.

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

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.

Important Rules:

inBankCode and paymentMethods are mutually exclusive: when inBankCode is omitted, paymentMethods is required, and vice versa.
Dynamic filtering and top-to-bottom ordering via paymentMethods also applies to the Global Cashier (/global/cashier/collect/apply).

How to Choose?

When to Choose Checkout Mode
When to Choose Component 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

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

Quick start

Merchant Guide

Common Payment

Global Payment

Unified API

End To End Testing

Appendix

Merchant FAQ

Checkout Integration Modes

Checkout Mode

Component Mode

Comparison & Selection Matrix

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

How to Choose?

Checkout Mode

Component Mode

​Comparison & Selection Matrix

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

​How to Choose?

​Related Topics

Comparison & Selection Matrix

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

How to Choose?

Related Topics