URL: /paas/fincard-virtual

---
title: 'FinCard Virtual'
description: 'Virtual card issuance, management, and crypto wallet integration'
---

# FinCard Virtual

FinCard Virtual provides comprehensive card issuance and management APIs, supporting virtual cards, physical cards, shared (budget) cards, and gift cards across Visa, MasterCard, and Discover networks.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/fincard/virtual`
</Info>

<Note>
  All endpoints use `POST` method with JSON body. The response envelope is always `{ "success": bool, "code": int, "msg": string, "data": ... }`.
</Note>

---

## API Groups

<CardGroup cols={2}>
  <Card title="Common" icon="globe" href="/paas/fincard-virtual/common">
    Reference data: countries, cities, mobile codes, file uploads, work orders
  </Card>
  <Card title="Accounts" icon="wallet" href="/paas/fincard-virtual/accounts">
    Merchant accounts, balances, ledger transactions, fund transfers
  </Card>
  <Card title="Crypto Wallet" icon="bitcoin" href="/paas/fincard-virtual/wallet">
    Coin list, wallet addresses, crypto deposit/withdrawal transactions
  </Card>
  <Card title="Cards" icon="credit-card" href="/paas/fincard-virtual/cards">
    Card types, issuance, deposit/withdraw, freeze/unfreeze, cancel, transactions
  </Card>
  <Card title="Card Holders" icon="id-card" href="/paas/fincard-virtual/card-holders">
    KYC cardholder creation (B2B/B2C), update, approval status, listing
  </Card>
  <Card title="Webhooks" icon="bell" href="/paas/fincard-virtual/webhooks">
    Real-time event notifications for card operations and transactions
  </Card>
  <Card title="Work Orders" icon="clipboard-list" href="/paas/fincard-virtual/api/work-list">
    Work order management and submission
  </Card>
</CardGroup>

---

## Card Issuance Flows

<CardGroup cols={2}>
  <Card title="Issuance Processes" icon="diagram-project" href="/paas/fincard-virtual/card-issuance-flows">
    Step-by-step flows for Virtual, Physical, Shared, and Gift cards
  </Card>
</CardGroup>

---

## Quick Start: Issue a Virtual Card

### Step 1: Get Available Card Types
```bash
POST /api/v2.1/fincard/virtual/card/v2/cardTypes
Body: {}
```

### Step 2: Create Cardholder (if required)
```bash
POST /api/v2.1/fincard/virtual/card/holder/v2/create
Body: { "cardHolderModel": "B2B", "cardTypeId": 111001, ... }
```

### Step 3: Create Card
```bash
POST /api/v2.1/fincard/virtual/card/v2/openCard
Body: { "merchantOrderNo": "...", "cardTypeId": 111001, "amount": 100 }
```

### Step 4: Query Card Info
```bash
POST /api/v2.1/fincard/virtual/card/info
Body: { "cardNo": "FC-XXXX" }
```

### Step 5: Get Sensitive Info (Card Number, CVV, Expiry)
```bash
POST /api/v2.1/fincard/virtual/card/info/sensitive
Body: { "cardNo": "FC-XXXX" }
```

---

## Endpoint Summary

| Group | Endpoints | Description |
|-------|-----------|-------------|
| **Common** | 7 | Reference data, file upload, work orders |
| **Accounts** | 8 | Account CRUD, balances, ledger, transfers |
| **Crypto Wallet** | 4 | Coins, addresses, deposit/withdraw history |
| **Cards** | 21 | Full card lifecycle + 5 transaction query types |
| **Card Holders** | 6 | KYC holder management (B2B/B2C) |
| **Webhooks** | 1 | Event callback receiver |
| **Work Orders** | 2 | Work order management |
| **Total** | **49** | |

---

## Authentication

All requests require standard FinHub authentication headers:

| Header | Required | Description |
|--------|----------|-------------|
| `X-Tenant-ID` | Yes | Tenant identifier |
| `Authorization` | Yes | Bearer JWT token |
| `Content-Type` | Yes | `application/json` |

---

## Environments

| Environment | Base URL |
|-------------|----------|
| **Sandbox** | `https://sandbox.finhub.cloud/api/v2.1/fincard/virtual` |
| **Integration** | `https://api-beta.finhub.cloud/api/v2.1/fincard/virtual` |
| **Production** | `https://api.finhub.cloud/api/v2.1/fincard/virtual` |