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

---

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.

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

---

2. Physical Card

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

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)

---

3. Shared Card (BUDGET_CARD)

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

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

---

4. Gift Card

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

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