Cards - As a Service

Cards

bunq's card issuing API lets you create and manage Mastercard debit cards linked directly to your users' monetary accounts. Cards work everywhere Mastercard is accepted — online, in-store, and in digital wallets.

---

The paradigm

In bunq, every card is linked to a monetary account. Spending on the card debits that account in real time. You control the card lifecycle — from creation and PIN management to spending limits, freezing, and cancellation — entirely through the API.

bunq issues two card types:

• Virtual cards — available immediately after creation, delivered as a card number, expiry, and CVC. Ideal for online purchases, subscriptions, and digital wallet provisioning.

• Physical cards — shipped to the cardholder's address. Same API creation flow; delivery typically takes 5–7 business days within the EU.

Key things to understand:

• One card, one account. A card is always linked to exactly one monetary account. Changing the linked account is supported — useful if you want to redirect spending to a different balance.

• Spending limits. You can set daily, weekly, or monthly spending limits per card via the API. You can also restrict the card to specific MCC (merchant category) codes.

• CVC2 generation. For virtual cards, you generate a fresh CVC2 on demand via API. CVC2s are valid for a short window and regenerated each time — there is no stored static CVC.

• Freezing and unfreezing. Cards can be frozen instantly via API (e.g. if a user reports it missing) and unfrozen just as quickly.

• Callbacks. Register a notification filter to receive real-time events for authorisations, settlements, and declines.

---

Flow overview

Issuing a virtual card:

Your platform                    bunq API
─────────────                    ────────
POST /card-virtual           →   Creates card, returns PAN + expiry
POST /generated-cvc2         →   Returns a fresh CVC2 for the card
                             ←   Card ready for use

Handling a transaction:

Cardholder makes a purchase       bunq API         Your platform
──────────────────────────        ────────         ─────────────
Card presented at merchant    →   Authorisation
                              →   Callback: CARD_TRANSACTION_AUTHORISED → Your webhook
Settlement (T+1)              →   Payment object created on account

---

Relevant API endpoints

Action	Endpoint
Issue a virtual card	POST /v1/user/{userID}/card-virtual
List cards for a user	GET /v1/user/{userID}/card
Get card details	GET /v1/user/{userID}/card/{itemID}
Update card (limits, freeze, link account)	PUT /v1/user/{userID}/card/{itemID}
Generate a CVC2	POST /v1/user/{userID}/card/{cardID}/generated-cvc2
List card transactions	GET /v1/user/{userID}/monetary-account/{accountID}/mastercard-action
Register card callbacks	POST /v1/user/{userID}/notification-filter-url

---

Card object highlights

The card object returned after creation includes:

• id — your persistent reference for this card

• pan_link — a link to the card's full PAN (fetched separately for PCI compliance reasons)

• expiry_date — in YYYY-MM format

• status — ACTIVE, DEACTIVATED, SUSPENDED, EXPIRED

• limit — array of spending limit objects, each with value, currency, and type (daily/weekly/monthly)

• primary_account_number_four_digit — last four digits, safe to display in your UI

---

Common integration patterns

Pattern 1 — Instant virtual card per user. Issue a virtual card at the end of KYC + account creation. The user gets a card they can add to Apple Pay / Google Pay immediately, without waiting for a physical card.

Pattern 2 — Expense cards with limits. Issue cards to employees or contractors with a fixed monthly spending limit and MCC restrictions. Adjust limits dynamically as budgets change — no need to reissue the card.

Pattern 3 — Disposable cards. Issue a virtual card for a single transaction or campaign, then cancel it. Eliminates the risk of recurring merchant charges or data exposure from a compromised PAN.

Pattern 4 — Freeze on suspicious activity. Use your own fraud signals to freeze a card instantly via PUT /card/{id} with status: SUSPENDED. Unfreeze just as quickly once verified. Pair with transaction callbacks to act in near-real-time.

---

Physical card orders require a verified postal address on the sub-user's profile. Make sure the user's address is set before calling the physical card creation endpoint.

CVC2 values must not be stored. Generate them on demand and display them directly to the cardholder. Storing CVC2s violates PCI DSS requirements.