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

# Card Payments Overview

> Overview of HaiPay card payments (supporting both credit and debit cards across VISA / MasterCard / JCB / AMEX / Diners / Discover) and mobile wallets (Apple Pay, Google Pay), transaction modes, limits, payment codes, and integration paths.

> [!WARNING]
>
> Before integrating, please review the [**API Description and Common Rules**](https://doc.haipay.net/en/guide/api-conventions.md).

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](https://doc.haipay.net/en/payments/supported-regions.md), covering one-time collection (CIT), merchant-initiated transactions (MIT), and fixed-term recurring subscriptions.

> [card] [1. Choose Checkout Integration](https://doc.haipay.net/en/payments/integration-modes.md)
>
> Compare **Checkout Mode (`payUrl` redirect)** and **Component Mode (`clientToken` embed)**.

> [card] [2. Choose Transaction Mode](https://doc.haipay.net/en/payments/cit-mit.md)
>
> Understand **One-Time CIT**, **On-Demand MIT**, and **Fixed-Term Subscriptions** to match your billing model.

> [card] [3. Sandbox Test Cards](https://doc.haipay.net/en/payments/test-cards.md)
>
> 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`](https://doc.haipay.net/en/api-reference/card/collect-apply) | [Checkout Mode](https://doc.haipay.net/en/payments/payment-link.md) or [Component Mode (`mode: 'payment'`)](https://doc.haipay.net/en/payments/frontend-payment-element) | 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`](https://doc.haipay.net/en/api-reference/card/mit-apply) (See [MIT Guide](https://doc.haipay.net/en/payments/card-mit.md)) | 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`](https://doc.haipay.net/en/api-reference/subscription/subscription-apply) (See [Subscription Guide](https://doc.haipay.net/en/payments/subscription.md)) | [Checkout Mode](https://doc.haipay.net/en/payments/payment-link.md) or [Component Mode (**`mode: 'subscription'`**)](https://doc.haipay.net/en/payments/frontend-payment-element) | 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](https://doc.haipay.net/en/payments/payment-link.md)**: Redirect the user to HaiPay's hosted payment page using `payUrl` for quick verification with minimal frontend work.
* **[Component Mode](https://doc.haipay.net/en/payments/frontend-payment-element.md)**: 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**](https://doc.haipay.net/en/payments/integration-modes.md).

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

> [!NOTE]
>
> **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](https://doc.haipay.net/en/payments/global-cashier.md).

## Core APIs & Interactive Playground

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

> [card] [Card Collection Apply](https://doc.haipay.net/en/api-reference/card/collect-apply.md)
>
> `POST /usd/collect/apply` — Create a one-time CIT collection order supporting credit/debit cards, Apple Pay, and Google Pay.

> [card] [MIT Collection Apply](https://doc.haipay.net/en/api-reference/card/mit-apply.md)
>
> `POST /usd/mit/apply` — Initial card-saving charge (omit `tokenID`) or subsequent off-session MIT charge (pass `tokenID`).

> [card] [Collection Order Query](https://doc.haipay.net/en/api-reference/card/collect-query.md)
>
> `POST /usd/collect/query` — Query the final payment status and fee breakdown of a collection or MIT order.

> [card] [Refund Apply & Query](https://doc.haipay.net/en/api-reference/card/refund-apply.md)
>
> `POST /usd/refund/apply` and [Refund Query `/usd/refund/refundQuery`](https://doc.haipay.net/en/api-reference/card/refund-query) — Full or partial refunds (`refundAmount`).

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

> [tab] Option 1: Single Payment Method (pass inBankCode)
>
> To specify card payment only, pass `payType: "BANK_TRANSFER"` and `inBankCode: "CREDIT_CARD"` (omit `paymentMethods`):
>
> ```json theme={null}
> {
>   "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..."
> }
> ```

> [tab] Option 2: Dynamic Display & Order (pass paymentMethods)
>
> 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:
>
> ```json theme={null}
> {
>   "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

> [!TIP]
>
> * **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.

> [!CAUTION]
>
> 1. **PCI Compliance**: Directly violates PCI DSS (Payment Card Industry Data Security Standard) requirements.
> 2. **Insufficient Isolation**: Third-party `WebView` or wrapper `iframe` containers may fail to provide adequate security isolation.
> 3. **Man-in-the-Middle Risk**: Malicious host apps may intercept or tamper with sensitive cardholder data.
> 4. **Phishing Risk**: Users cannot verify that they are entering sensitive credentials in a trusted environment.
>
> Always use [Checkout Mode](https://doc.haipay.net/en/payments/payment-link.md) or the official [Component Mode](https://doc.haipay.net/en/payments/frontend-payment-element.md) in a standard, trusted browser environment.

## Explore Related Guides

> [card] [Apple Pay & Google Pay](https://doc.haipay.net/en/payments/apple-pay-google-pay.md)
>
> Device, OS, and browser requirements (`#supported-browsers`) and wallet configuration details.

> [card] [CIT vs. MIT Transaction Modes](https://doc.haipay.net/en/payments/cit-mit.md)
>
> Deep dive into on-session customer-initiated vs. off-session merchant-initiated transactions and subscriptions.

> [card] [MIT & Subscription Guides](https://doc.haipay.net/en/payments/card-mit.md)
>
> Integrate [MIT Payments (`/usd/mit/apply`)](https://doc.haipay.net/en/payments/card-mit) or [Fixed-Term Subscriptions (`/subscription/apply`)](https://doc.haipay.net/en/payments/subscription).

> [card] [Supported Regions & Test Cards](https://doc.haipay.net/en/payments/supported-regions.md)
>
> Browse the [62 supported countries/regions](https://doc.haipay.net/en/payments/supported-regions.md) and [sandbox test card numbers](https://doc.haipay.net/en/payments/test-cards.md).


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