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)
| 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 |
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 |
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 |
