Card Payments Overview

Before integrating, please review the API Description and Common Rules.

HaiPay Card Payments support both credit cards and debit cards across major global card networks (VISA, MasterCard, JCB, American Express, Diners Club, Discover) as well as mobile wallets (Apple Pay, Google Pay) in 62 supported countries and regions, covering one-time collection (CIT), merchant-initiated transactions (MIT), and fixed-term recurring subscriptions.

1. Choose Checkout Integration

Compare Checkout Mode (payUrl redirect) and Component Mode (clientToken embed).

2. Choose Transaction Mode

Understand One-Time CIT, On-Demand MIT, and Fixed-Term Subscriptions to match your billing model.

3. Sandbox Test Cards

Simulate successful payments, issuer declines, and post-transaction disputes in the test environment.

Transaction Modes & Capability Matrix

Select the appropriate API endpoint based on whether you are charging once, saving a card for merchant-scheduled/usage-based charges, or running a fixed-cycle subscription plan:

Transaction Mode	Initiator & Session State	Core API Endpoint	Frontend Integration	Typical Use Cases
One-Time Collection (CIT)	Cardholder actively pays on-session	`POST /usd/collect/apply`	Checkout Mode or Component Mode (`mode: 'payment'`)	E-commerce checkout, one-off purchases, manual top-ups
MIT (Merchant-Initiated Transaction)	Initial on-session user authorization (CIT), followed by off-session merchant charges	`POST /usd/mit/apply` (See MIT Guide)	Initial charge via Checkout Mode or Component Mode (`mode: 'payment'`); subsequent charges via server with `tokenID`	Usage-based billing, auto top-ups, merchant-scheduled recurring billing
Fixed-Term Subscription	Initial on-session user authorization, followed by HaiPay-scheduled recurring deductions	`POST /subscription/apply` (See Subscription Guide)	Checkout Mode or Component Mode (`mode: 'subscription'`)	Monthly/annual VIP memberships, standard SaaS plans

Checkout Integration at a Glance

HaiPay decouples payment methods from checkout integration modes. Every create endpoint returns both payUrl and clientToken:

Checkout Mode: Redirect the user to HaiPay’s hosted payment page using payUrl for quick verification with minimal frontend work.
Component Mode: Mount the pre-built Component inside your own webpage using clientToken for optimal build efficiency so users pay with cards, Apple Pay, or Google Pay without leaving your site.

For architectural diagrams and a full comparison of developer effort, UI customization, PCI DSS scope, and code snippets, see Checkout Integration Modes.

Payment Methods, Codes & Limits

Card (credit and debit) and mobile wallet transactions are priced and settled in USD (using your USD appId), with a single-transaction limit of 0.99 – 1000 USD:

Currency	Payment Type (`payType`)	Payment Code (`inBankCode`)	Single Limit (USD)	Status	Card Network / Wallet
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	VISA
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	MasterCard
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	JCB
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	American Express (AMEX)
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	Diners Club (DINERS)
USD	`BANK_TRANSFER`	`CREDIT_CARD`	0.99 - 1000	Available	Discover (DISCOVER)
USD	`EWALLET`	`GOOGLE_PAY`	0.99 - 1000	Available	Google Pay
USD	`EWALLET`	`APPLE_PAY`	0.99 - 1000	Available	Apple Pay

Mutual Exclusivity between inBankCode and paymentMethods:

Pass inBankCode when specifying a single payment method (leave paymentMethods empty).
Pass paymentMethods (comma-separated, e.g., "GOOGLE_PAY,CREDIT_CARD") to dynamically control which payment methods are displayed and their top-to-bottom display order (leave inBankCode empty). For example, passing "GOOGLE_PAY,CREDIT_CARD" displays only Google Pay followed by Credit Card from top to bottom.
This dynamic display and ordering capability also maps to the Global Cashier.

Core APIs & Interactive Playground

For complete field definitions, signature rules, response schemas, and live testing, jump to the API Reference:

Card Collection Apply

POST /usd/collect/apply — Create a one-time CIT collection order supporting credit/debit cards, Apple Pay, and Google Pay.

MIT Collection Apply

POST /usd/mit/apply — Initial card-saving charge (omit tokenID) or subsequent off-session MIT charge (pass tokenID).

Collection Order Query

POST /usd/collect/query — Query the final payment status and fee breakdown of a collection or MIT order.

Refund Apply & Query

POST /usd/refund/apply and Refund Query /usd/refund/refundQuery — Full or partial refunds (refundAmount).

Request Examples (`/usd/collect/apply`)

Option 1: Single Payment Method (pass inBankCode)
Option 2: Dynamic Display & Order (pass paymentMethods)

To specify card payment only, pass payType: "BANK_TRANSFER" and inBankCode: "CREDIT_CARD" (omit paymentMethods):

{
  "appId": 1054,
  "orderId": "M233323000059",
  "amount": "299.99",
  "phone": "+12025551234",
  "email": "robert.taylor@gmail.com",
  "name": "Robert Taylor",
  "payType": "BANK_TRANSFER",
  "inBankCode": "CREDIT_CARD",
  "callBackUrl": "https://merchant.com/payment/success",
  "callBackFailUrl": "https://merchant.com/payment/fail",
  "cancelUrl": "https://merchant.com/payment/cancel",
  "notifyUrl": "https://merchant.com/api/notify",
  "subject": "Order M233323000059",
  "partnerUserId": "149597870",
  "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
}

To display multiple payment methods and control their top-to-bottom display order, pass paymentMethods (omit inBankCode). The example below renders Google Pay first and Cards second from top to bottom:

{
  "appId": 1054,
  "orderId": "M233323000060",
  "amount": "299.99",
  "phone": "+12025551234",
  "email": "robert.taylor@gmail.com",
  "name": "Robert Taylor",
  "payType": "BANK_TRANSFER",
  "paymentMethods": "GOOGLE_PAY,CREDIT_CARD",
  "callBackUrl": "https://merchant.com/payment/success",
  "callBackFailUrl": "https://merchant.com/payment/fail",
  "cancelUrl": "https://merchant.com/payment/cancel",
  "notifyUrl": "https://merchant.com/api/notify",
  "subject": "Order M233323000060",
  "partnerUserId": "149597870",
  "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
}

Compliance, Disputes & Security

Dispute Window & Handling Fee: Cardholders may file a dispute within 180 days of the transaction date. Each dispute incurs a 20 USD dispute handling fee.
Response Options: Upon receiving a dispute notification, you have two choices:
- Accept the dispute: Confirm to the issuing bank that you do not contest the refund amount.
- Contest / Rebuttal: Submit supporting evidence through a guided flow to defend your position, which incurs an additional 20 USD rebuttal fee. If the issuing bank rules in favor of the cardholder, the rebuttal fee is deducted and the transaction amount is refunded.
Fee Refund Policy: If you win the dispute, HaiPay refunds the rebuttal fee. However, unless otherwise specified in your HaiPay contract, the initial dispute handling fee is non-refundable under all circumstances.

PCI Compliance: Directly violates PCI DSS (Payment Card Industry Data Security Standard) requirements.
Insufficient Isolation: Third-party WebView or wrapper iframe containers may fail to provide adequate security isolation.
Man-in-the-Middle Risk: Malicious host apps may intercept or tamper with sensitive cardholder data.
Phishing Risk: Users cannot verify that they are entering sensitive credentials in a trusted environment.

Always use Checkout Mode or the official Component Mode in a standard, trusted browser environment.

Apple Pay & Google Pay

Device, OS, and browser requirements (#supported-browsers) and wallet configuration details.

CIT vs. MIT Transaction Modes

Deep dive into on-session customer-initiated vs. off-session merchant-initiated transactions and subscriptions.

MIT & Subscription Guides

Integrate MIT Payments (/usd/mit/apply) or Fixed-Term Subscriptions (/subscription/apply).

Supported Regions & Test Cards

Browse the 62 supported countries/regions and sandbox test card numbers.

Quick start

Merchant Guide

Common Payment

Global Payment

Unified API

End To End Testing

Appendix

Merchant FAQ

Card Payments Overview

1. Choose Checkout Integration

2. Choose Transaction Mode

3. Sandbox Test Cards

Transaction Modes & Capability Matrix

Checkout Integration at a Glance

Payment Methods, Codes & Limits

Core APIs & Interactive Playground

Card Collection Apply

MIT Collection Apply

Collection Order Query

Refund Apply & Query

Request Examples (`/usd/collect/apply`)

Compliance, Disputes & Security

Apple Pay & Google Pay

CIT vs. MIT Transaction Modes

MIT & Subscription Guides

Supported Regions & Test Cards

1. Choose Checkout Integration

2. Choose Transaction Mode

3. Sandbox Test Cards

​Transaction Modes & Capability Matrix

​Checkout Integration at a Glance

​Payment Methods, Codes & Limits

​Core APIs & Interactive Playground

Card Collection Apply

MIT Collection Apply

Collection Order Query

Refund Apply & Query

​Request Examples (/usd/collect/apply)

​Compliance, Disputes & Security

​Explore Related Guides

Apple Pay & Google Pay

CIT vs. MIT Transaction Modes

MIT & Subscription Guides

Supported Regions & Test Cards

Transaction Modes & Capability Matrix

Checkout Integration at a Glance

Payment Methods, Codes & Limits

Core APIs & Interactive Playground

Request Examples (`/usd/collect/apply`)

Compliance, Disputes & Security

Explore Related Guides