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

# Card Issuance Flows

> 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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` |