Virtual Cards
Issue USD virtual cards in real time — create, fund, freeze and terminate programmatically, with granular spend controls and instant transaction webhooks.
1. Create a cardholder
POST /v1/cardholders
cURL
curl https://api.finlogic.com/v1/cardholders \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"first_name": "Adaeze",
"last_name": "Okafor",
"email": "adaeze@example.com",
"phone": "+2348012345678",
"id_type": "nin",
"id_number": "12345678901"
}'
2. Issue a card
POST /v1/cards
cURL
curl https://api.finlogic.com/v1/cards \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"cardholder_id": "ch_2d8k4m1x",
"currency": "USD",
"brand": "visa",
"initial_balance": 50,
"controls": {
"spend_limit": 1000,
"spend_interval": "monthly",
"blocked_categories": ["gambling"]
}
}'
Response · 201 Created
{
"id": "cd_7p1q9r3s",
"status": "active",
"brand": "visa",
"currency": "USD",
"balance": 50,
"masked_pan": "411111******1111",
"expiry_month": "07",
"expiry_year": "2029",
"created_at": "2026-07-10T10:02:51Z"
}
Full PAN and CVV are never returned in API responses. Retrieve them once via a short-lived secure URL: GET /v1/cards/{id}/secure-details.
3. Fund & withdraw
POST /v1/cards/{id}/fund
POST /v1/cards/{id}/withdraw
cURL
curl https://api.finlogic.com/v1/cards/cd_7p1q9r3s/fund \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 200 }'
4. Freeze / terminate
POST /v1/cards/{id}/freeze
POST /v1/cards/{id}/unfreeze
DELETE /v1/cards/{id}
Freezing declines all new authorisations instantly but keeps the card and balance intact. Terminating is permanent — the remaining balance is returned to your wallet.
Transactions
GET /v1/cards/{id}/transactions
Every authorisation, settlement, refund and decline also fires a card.transaction webhook in real time:
Webhook · card.transaction
{
"id": "evt_8m2x5c1v",
"type": "card.transaction",
"data": {
"card_id": "cd_7p1q9r3s",
"type": "authorization",
"status": "approved",
"amount": 12.99,
"currency": "USD",
"merchant": "NETFLIX.COM",
"merchant_category": "digital_goods",
"created_at": "2026-07-10T18:22:31Z"
}
}
Insufficient funds declines: repeated declines for insufficient balance can trigger automatic risk freezes by the card network. Keep cards funded or set
controls.spend_limit conservatively.