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:

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

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

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.

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

Monitor cardholder approval via Cardholder List or Webhooks. Proceed to card creation only when status=pass_audit.

2. Physical Card

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

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)

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

3. Shared Card (BUDGET_CARD)

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

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

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

4. Gift Card

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

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`

Connectors

PaaS Journey

PaaS Operations

FinCard Virtual

Card Issuance Flows

Card Issuance Flows

Introduction

Architecture Overview

Prerequisites

Choose Your Card Type

Common Headers

1. Virtual Card (PREPAID_CARD)

2. Physical Card

3. Shared Card (BUDGET_CARD)

4. Gift Card

Gift Card Restrictions

Flow Comparison

​Card Issuance Flows

​Introduction

​Architecture Overview

​Prerequisites

​Choose Your Card Type

​Common Headers

​1. Virtual Card (PREPAID_CARD)

​2. Physical Card

​3. Shared Card (BUDGET_CARD)

​4. Gift Card

​Gift Card Restrictions

​Flow Comparison

Card Issuance Flows

Introduction

Architecture Overview

Prerequisites

Choose Your Card Type

Common Headers

1. Virtual Card (PREPAID_CARD)

2. Physical Card

3. Shared Card (BUDGET_CARD)

4. Gift Card

Gift Card Restrictions

Flow Comparison