URL: /paas/fincard-virtual/card-issuance-flows

---
title: 'Card Issuance Flows'
description: 'Step-by-step processes for Virtual, Physical, Shared, and Gift card issuance'
---

# Card Issuance Flows

## Introduction

FinCard Virtual is a card-issuing service built on the FinCard platform. It enables tenants to programmatically issue, manage, and monitor prepaid cards — virtual or physical — for their end customers (B2B or B2C).

All endpoints are available for interactive testing at **`https://sandbox.finhub.cloud`**. Each endpoint page includes a **Try It** panel where you can send live requests against the sandbox.

---

### Architecture Overview

```
Your Application
      │
      ▼
FinHub BFF  (/api/v2.1/fincard/virtual/...)
      │
      ├── Playground mode  →  in-memory JPA/MariaDB (no external calls)
      └── Integration mode →  FinCard Virtual Production API (RSA-signed)
```

The BFF operates in one of two modes based on tenant configuration:

| Mode | Description | Use case |
|------|-------------|----------|
| **Playground** | Fully simulated — all data stored in sandbox DB | Development & testing |
| **Integration** | Live calls to FinCard Virtual API (RSA-signed) | Production |

---

### Prerequisites

Before issuing any card, ensure:

1. **Tenant credentials** — valid `X-Tenant-ID` header on every request
2. **Account funded** — the tenant's WALLET account has sufficient balance
3. **Card BINs available** — call `POST /card/v2/cardTypes` to discover available BINs and their requirements
4. **Cardholder created** (if `needCardHolder: true` on the BIN) — cardholder must reach `status: pass_audit` before a card can be linked

<Note>
  All API bodies are raw JSON strings (`Content-Type: application/json`). The BFF forwards them directly to FinCard Virtual after signature verification.
</Note>

---

### Choose Your Card Type

```
Start
  │
  ├─► Need multiple cards sharing a pool? ──► Shared Card (BUDGET_CARD)
  │
  ├─► Physical card issued offline? ────────► Physical Card
  │
  ├─► Redemption URL only (no card number)? ► Gift Card
  │
  └─► Standard virtual prepaid? ────────────► Virtual Card (PREPAID_CARD)
```

| Card Type | BIN Mode | BIN Type | Category |
|-----------|----------|----------|----------|
| **Virtual** | `PREPAID_CARD` | `Virtual` | `PURCHASE` / `SUBSCRIPTION` |
| **Physical** | `PREPAID_CARD` | `Physical` | `PHYSICAL` |
| **Shared** | `BUDGET_CARD` | `Virtual` | `PURCHASE` |
| **Gift** | `PREPAID_CARD` | `Virtual` | `GIFT` |

---

### Common Headers

Every request requires:

| Header | Description |
|--------|-------------|
| `X-Tenant-ID` | Your tenant identifier |
| `Content-Type` | `application/json` |

---

Four card issuance processes, each with a distinct flow. All share the same API endpoints but differ in required steps and configuration.

---

## 1. Virtual Card (PREPAID_CARD)

The standard flow for issuing virtual prepaid cards.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN -->|needCardHolder?| CheckHolder{CheckHolder}
    CheckHolder -->|Yes| CreateHolder[CreateHolder]
    CheckHolder -->|No| CreateCard[CreateCard]
    CreateHolder --> WaitApproval[WaitApproval]
    WaitApproval -->|Approved| CreateCard
    CreateCard --> QueryInfo[QueryInfo]
    QueryInfo --> GetSensitive[GetSensitive]
    GetSensitive --> E([Ready to use])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get available card BINs. Filter `mode=PREPAID_CARD`, `type=Virtual` |
| 2 | Check `needCardHolder` | If `true`, create cardholder first |
| 3 | `POST /card/holder/v2/create` | Create cardholder (B2B or B2C based on `metadata.cardHolderModel`) |
| 4 | `POST /card/v2/openCard` | Create card with `holderId` + initial `amount` |
| 5 | `POST /card/info` | Query card info (status, balance) |
| 6 | `POST /card/info/sensitive` | Get encrypted card number, CVV, expiry |

<Note>
  Monitor cardholder approval via [Cardholder List](/paas/fincard-virtual/card-holders) or [Webhooks](/paas/fincard-virtual/webhooks). Proceed to card creation only when `status=pass_audit`.
</Note>

---

## 2. Physical Card

Physical cards are purchased offline in bulk, then assigned and activated via API.

```mermaid
flowchart TD
    S(( )) --> PurchaseOffline[PurchaseOffline]
    PurchaseOffline --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> AssignCard[AssignCard]
    AssignCard -->|webhook| ReceiveCode[ReceiveCode]
    ReceiveCode --> ActivateCard[ActivateCard]
    ActivateCard --> GetSensitive[GetSensitive]
    GetSensitive --> E([Ready to use])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | — | Customer purchases physical cards offline from BD |
| 2 | `POST /card/v2/cardTypes` | Get BIN config. Filter `type=Physical` |
| 3 | `POST /card/holder/v2/create` | Create cardholder (if `needCardHolder=true`) |
| 4 | `POST /card/v2/openCard` | Create card with `cardNumber` (from physical card) |
| 5 | Webhook: `activation_code` | Receive activation code via webhook or cardholder email |
| 6 | `POST /card/activate` | Activate with `pin` (6 digits) + `activeCode` |
| 7 | `POST /card/info/sensitive` | Get card number, CVV, expiry (available after activation) |

<Warning>
  Before activation, `card/info/sensitive` returns limited data. Full card details (number, CVV, expiry) are only available after successful activation.
</Warning>

---

## 3. Shared Card (BUDGET_CARD)

Multiple cards share the same wallet. Deposit = allocate credit limit, Withdraw = reduce credit limit.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> CreateAccount[CreateAccount]
    CreateAccount --> FundAccount[FundAccount]
    FundAccount --> CreateCard1[CreateCard 1]
    FundAccount --> CreateCard2[CreateCard 2]
    CreateCard1 --> AllocateCredit[AllocateCredit]
    CreateCard2 --> AllocateCredit
    AllocateCredit --> E([Cards ready])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get BIN config. Filter `mode=BUDGET_CARD` |
| 2 | `POST /card/holder/v2/create` | Create cardholder (if needed) |
| 3 | `POST /account/create` | Create MARGIN account for shared pool |
| 4 | `POST /account/transfer` | Fund MARGIN from WALLET |
| 5-6 | `POST /card/v2/openCard` | Create cards with `accountId` pointing to shared account |
| 7 | `POST /card/deposit` | Top-up = allocate credit limit to each card |

<Note>
  - **Deposit** on a shared card = allocating credit from the shared pool
  - **Withdraw** on a shared card = reducing the credit limit
  - All cards share the same underlying MARGIN account balance
</Note>

---

## 4. Gift Card

Gift cards return only a redemption URL. No card number/CVV/expiry. No deposit/withdraw/freeze/unfreeze.

```mermaid
flowchart TD
    S(( )) --> GetCardBIN[GetCardBIN]
    GetCardBIN --> CreateHolder[CreateHolder]
    CreateHolder --> CreateCard[CreateCard]
    CreateCard --> GetSensitive[GetSensitive]
    GetSensitive --> E([Share URL with recipient])
```

| Step | API | Description |
|------|-----|-------------|
| 1 | `POST /card/v2/cardTypes` | Get BIN config. Filter `category=GIFT` |
| 2 | `POST /card/holder/v2/create` | Create cardholder (if needed) |
| 3 | `POST /card/v2/openCard` | Create gift card with initial amount |
| 4 | `POST /card/info/sensitive` | Returns only `activateUrl` (redemption page) |

### Gift Card Restrictions

| Feature | Supported |
|---------|-----------|
| Card number / CVV / Expiry | **No** — only `activateUrl` |
| Deposit | **No** |
| Withdraw | **No** |
| Freeze / UnFreeze | **No** |
| Cancel | Yes |
| Card Info | Yes (basic status only) |

---

## Flow Comparison

| Feature | Virtual | Physical | Shared | Gift |
|---------|---------|----------|--------|------|
| **Mode** | PREPAID_CARD | PREPAID_CARD | BUDGET_CARD | PREPAID_CARD |
| **Type** | Virtual | Physical | Virtual | Virtual |
| **Category** | PURCHASE/SUBSCRIPTION | PHYSICAL | PURCHASE | GIFT |
| **Cardholder** | Optional | Optional | Optional | Optional |
| **Card Number Input** | No | Yes (offline) | No | No |
| **Activation** | Auto | Manual (PIN + code) | Auto | Auto |
| **Shared Account** | No | No | Yes (MARGIN) | No |
| **Deposit/Withdraw** | Yes | Yes | Yes (credit allocation) | No |
| **Freeze/UnFreeze** | Yes | Yes | Yes | No |
| **Sensitive Info** | Full | After activation | Full | Only `activateUrl` |