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

# Cards

> Card issuance, lifecycle management, and transaction queries

# Card APIs

Full card lifecycle: card types, issuance, balance, deposit/withdraw, freeze/unfreeze, cancel, activate (physical), PIN management, and 5 transaction query types.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/card/...`
</Info>

***

## Support Bins (Card Types)

Returns all available card types with pricing, features, and cardholder requirements.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/v2/cardTypes
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field                                | Type       | Description                                       |
| ------------------------------------ | ---------- | ------------------------------------------------- |
| `cardTypeId`                         | Long       | Card type ID (use in create card)                 |
| `organization`                       | String     | `Visa` / `MasterCard` / `Discover`                |
| `country`                            | String     | Issue country (ISO alpha-2)                       |
| `mode`                               | String     | `PREPAID_CARD` / `BUDGET_CARD` (shared)           |
| `bankCardBin`                        | String     | Card BIN (e.g. `531993`)                          |
| `type`                               | String     | `Virtual` / `Physical`                            |
| `category`                           | String     | `GIFT` / `PURCHASE` / `SUBSCRIPTION` / `PHYSICAL` |
| `cardName`                           | String     | Display name                                      |
| `cardDesc`                           | String     | Description                                       |
| `cardPrice`                          | BigDecimal | Card creation fee                                 |
| `cardPriceCurrency`                  | String     | Fee currency                                      |
| `support`                            | List       | Supported merchant names (reference only)         |
| `risk`                               | List       | High-risk merchants (card cancellation risk)      |
| `needCardHolder`                     | Boolean    | **true** = must create cardholder first           |
| `supportHolderRegin`                 | List       | Supported cardholder nationalities (ISO alpha-2)  |
| `supportHolderAreaCode`              | List       | Supported mobile area codes                       |
| `needDepositForActiveCard`           | Boolean    | Initial deposit required                          |
| `depositAmountMinQuotaForActiveCard` | BigDecimal | Min initial deposit                               |
| `depositAmountMaxQuotaForActiveCard` | BigDecimal | Max initial deposit                               |
| `fiatCurrency`                       | String     | Card currency (e.g. `USD`)                        |
| `balanceRetentionQuota`              | BigDecimal | Min balance for withdrawal                        |
| `status`                             | String     | `online` / `offline`                              |
| `rechargeCurrency`                   | String     | Deposit currency                                  |
| `rechargeMinQuota`                   | BigDecimal | Min deposit amount                                |
| `rechargeMaxQuota`                   | BigDecimal | Max deposit amount                                |
| `rechargeFeeRate`                    | BigDecimal | Deposit fee rate (`1` = 1%)                       |
| `rechargeFixedFee`                   | BigDecimal | Fixed deposit fee                                 |
| `rechargeDigital`                    | Integer    | Deposit amount decimal places                     |
| `enableActiveCard`                   | Boolean    | Card creation enabled                             |
| `enableDeposit`                      | Boolean    | Deposit enabled                                   |
| `enableFreeze`                       | Boolean    | Freeze enabled                                    |
| `enableUnFreeze`                     | Boolean    | Unfreeze enabled                                  |
| `metadata.cardHolderMaxCardLimit`    | Integer    | Max cards per cardholder                          |
| `metadata.cardHolderModel`           | String     | `B2B` / `B2C` (cardholder creation mode)          |
| `metadata.spendingControls[]`        | List       | Default spending limits                           |
| `metadata.supportSettingMcc`         | Boolean    | MCC whitelist/blacklist supported                 |

<Warning>
  `metadata.cardHolderModel` B2B/B2C is an internal code — it does NOT mean company vs individual. Use it to determine which cardholder creation fields are required.
</Warning>

***

## Create Card V2

Create a new virtual or physical card with initial deposit.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/v2/openCard
```

**Request:**

| Field             | Type       | Required | Description                                       |
| ----------------- | ---------- | -------- | ------------------------------------------------- |
| `merchantOrderNo` | String     | Yes      | Client transaction ID `[20..40]`                  |
| `holderId`        | Long       | No       | Cardholder ID (required if `needCardHolder=true`) |
| `cardTypeId`      | Long       | Yes      | Card type ID from cardTypes                       |
| `amount`          | BigDecimal | Yes      | Initial deposit. Range: `depositAmountMin..Max`   |
| `cardNumber`      | String     | No       | Required for physical card (offline card number)  |
| `accountId`       | Long       | No       | Account ID for shared card mode (BUDGET\_CARD)    |

**Response `data`:**

| Field              | Type       | Description                                        |
| ------------------ | ---------- | -------------------------------------------------- |
| `orderNo`          | String     | Platform transaction ID                            |
| `merchantOrderNo`  | String     | Client transaction ID                              |
| `cardNo`           | String     | **Card ID** (use for all subsequent operations)    |
| `currency`         | String     | Currency                                           |
| `amount`           | BigDecimal | Initial deposit amount                             |
| `fee`              | BigDecimal | Card creation fee                                  |
| `receivedAmount`   | BigDecimal | Amount credited to card                            |
| `receivedCurrency` | String     | Currency                                           |
| `type`             | String     | `create`                                           |
| `status`           | String     | `wait_process` / `processing` / `success` / `fail` |
| `description`      | String     | Status description                                 |
| `transactionTime`  | Long       | Millisecond timestamp                              |

<Note>
  `cardNo` is the unique card identifier. Use it for all card operations (info, deposit, withdraw, freeze, cancel).
</Note>

***

## Card Info

Get card details, status, and optional balance.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/info
```

**Request:**

| Field            | Type    | Required | Description                                  |
| ---------------- | ------- | -------- | -------------------------------------------- |
| `cardNo`         | String  | Yes      | Card ID                                      |
| `onlySimpleInfo` | Boolean | No       | Default `true`. Set `false` for balance info |

**Response `data`:**

| Field                    | Type       | Description                       |
| ------------------------ | ---------- | --------------------------------- |
| `cardTypeId`             | Long       | Card type ID                      |
| `holderId`               | Long       | Cardholder ID                     |
| `cardNo`                 | String     | Card ID                           |
| `status`                 | String     | See card statuses below           |
| `blocked`                | Boolean    | Card blocked by issuer            |
| `bindTime`               | Long       | Card creation time (ms)           |
| `balanceInfo.cardNo`     | String     | Card ID                           |
| `balanceInfo.amount`     | BigDecimal | Available balance                 |
| `balanceInfo.usedAmount` | BigDecimal | Amount used                       |
| `balanceInfo.currency`   | String     | Currency                          |
| `noPinPaymentAmount`     | BigDecimal | PIN-free payment limit (physical) |
| `spendingControls[]`     | List       | Spending controls                 |

**Card Statuses:**

| Status         | Description                          |
| -------------- | ------------------------------------ |
| `pending`      | Card being created                   |
| `un_activated` | Physical card waiting for activation |
| `Normal`       | Active and usable                    |
| `Freeze`       | Frozen (by merchant)                 |
| `Freezing`     | Freeze in progress                   |
| `UnFreezing`   | Unfreeze in progress                 |
| `canceling`    | Cancel in progress                   |
| `cancel`       | Cancelled (permanent)                |
| `fail`         | Card creation failed                 |

***

## Card Sensitive Info

Get encrypted card number, CVV, and expiry date. Decrypted with merchant's RSA private key.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/info/sensitive
```

**Request:** `{ "cardNo": "..." }`

**Response `data`:**

| Field         | Type   | Description                                |
| ------------- | ------ | ------------------------------------------ |
| `cardNumber`  | String | RSA-encrypted card number                  |
| `cvv`         | String | RSA-encrypted CVV                          |
| `expireDate`  | String | RSA-encrypted expiry date                  |
| `activateUrl` | String | Gift card redemption URL (gift cards only) |

<Note>
  **Gift cards** only return `activateUrl`. No card number, CVV, or expiry date.
</Note>

***

## Card Balance

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/balance
```

**Request:** `{ "cardNo": "..." }`

**Response `data`:** `{ cardNo, amount, usedAmount, currency }`

***

## Card Operations

All card operations follow the same request/response pattern.

### Common Request Fields

| Field             | Type       | Required | Description                   |
| ----------------- | ---------- | -------- | ----------------------------- |
| `cardNo`          | String     | Yes      | Card ID                       |
| `merchantOrderNo` | String     | Yes      | Client tx ID `[20..40]`       |
| `amount`          | BigDecimal | Varies   | Amount (for deposit/withdraw) |
| `clientRemark`    | String     | No       | Client remark `[0..50]`       |

### Common Response Fields

| Field             | Type       | Description                                        |
| ----------------- | ---------- | -------------------------------------------------- |
| `orderNo`         | String     | Platform tx ID                                     |
| `merchantOrderNo` | String     | Client tx ID                                       |
| `cardNo`          | String     | Card ID                                            |
| `currency`        | String     | Currency                                           |
| `amount`          | BigDecimal | Amount                                             |
| `fee`             | BigDecimal | Fee                                                |
| `receivedAmount`  | BigDecimal | Net amount                                         |
| `type`            | String     | Operation type                                     |
| `status`          | String     | `wait_process` / `processing` / `success` / `fail` |
| `description`     | String     | Description                                        |
| `transactionTime` | Long       | Millisecond timestamp                              |

### Endpoints

| Operation      | Path                | `type`        | Amount Required |
| -------------- | ------------------- | ------------- | --------------- |
| **Deposit**    | `/card/deposit`     | `deposit`     | Yes             |
| **Withdraw**   | `/card/withdraw`    | `withdraw`    | Yes (≥ 0.01)    |
| **Freeze**     | `/card/v2/freeze`   | `Freeze`      | No              |
| **UnFreeze**   | `/card/v2/unfreeze` | `UnFreeze`    | No              |
| **Cancel**     | `/card/cancel`      | `cancel`      | No              |
| **Update**     | `/card/v2/update`   | `card_update` | No              |
| **Update PIN** | `/card/updatePin`   | `update_pin`  | No              |

<Warning>
  **Cancel is permanent.** The card cannot be reactivated after cancellation.
</Warning>

### Update Card — Additional Fields

The Update endpoint also accepts:

| Field                     | Type       | Description                                 |
| ------------------------- | ---------- | ------------------------------------------- |
| `noPinPaymentAmount`      | BigDecimal | PIN-free limit (physical cards only)        |
| `spendingControls[]`      | List       | Spending limits (if `supportSetting=true`)  |
| `riskControls.allowedMcc` | List       | MCC whitelist (if `supportSettingMcc=true`) |
| `riskControls.blockedMcc` | List       | MCC blacklist                               |

<Note>
  Only one of `allowedMcc` or `blockedMcc` can be set. Send empty array `[]` to remove.
</Note>

### Update PIN — Rules

PIN must be 6 digits with these constraints:

* No 3+ consecutive repeated digits
* Not entirely ascending or descending
* No repeated 2-3 digit segments (e.g. 123123)

***

## Activate Card (Physical)

Activate a physical card with PIN and activation code.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/activate
```

**Request:**

| Field                | Type       | Required | Description                              |
| -------------------- | ---------- | -------- | ---------------------------------------- |
| `merchantOrderNo`    | String     | Yes      | Client tx ID `[20..40]`                  |
| `cardNo`             | String     | Yes      | Card ID                                  |
| `pin`                | String     | Yes      | 6-digit PIN                              |
| `activeCode`         | String     | Yes      | Activation code (from webhook or email)  |
| `noPinPaymentAmount` | BigDecimal | No       | PIN-free limit (0-2000 USD, default 500) |

**Response `data`:** `{ merchantOrderNo, cardNo, type: "card_activated", status, remark }`

***

## Transaction Queries

All transaction queries return `{ total, records[] }` with pagination (`pageNum`, `pageSize`).

### Card Purchase Transactions

Card fee and initial deposit records.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/purchase/transaction
```

### Card Operation Transactions (V1 / V2)

Card lifecycle operations (create, deposit, withdraw, freeze, cancel, etc.)

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/transaction       # V1
POST /api/v2.1/fincard/virtual/card/v2/transaction     # V2 (recommended)
```

**Filter:** `type` = `create` / `deposit` / `cancel` / `Freeze` / `UnFreeze` / `withdraw` / `update_pin` / `blocked` / `card_update` / `overdraft_statement`

### Card Authorization Transactions

Consumption (auth), refund, verification, reversal, and maintenance fee records.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/authorize/transaction
```

**Filter:** `type` = `auth` / `refund` / `verification` / `Void` / `maintain_fee`

**Statuses:** `authorized` / `failed` / `succeed`

### Card Authorization Fee Transactions

Fee records when card balance is insufficient for authorization fees.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/auth/fee/transaction
```

**Filter:** `tradeType` = `card_patch_fee` / `card_patch_cross_border`

### Card 3DS Transactions

3DS OTP codes, authorization URLs, and physical card activation codes.

```bash theme={null}
POST /api/v2.1/fincard/virtual/card/3ds/transaction
```

**Filter:** `type` = `third_3ds_otp` / `auth_url` / `activation_code`

| Field            | Type   | Description                                        |
| ---------------- | ------ | -------------------------------------------------- |
| `values`         | String | RSA-encrypted value (OTP, URL, or activation code) |
| `expirationTime` | Long   | Expiration time (ms)                               |