URL: /paas/fincard-virtual/cards

---
title: 'Cards'
description: '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
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
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
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
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
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
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
POST /api/v2.1/fincard/virtual/card/purchase/transaction
```

### Card Operation Transactions (V1 / V2)

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

```bash
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
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
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
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) |