> For the complete documentation index, see [llms.txt](https://partner.doc.bunq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://partner.doc.bunq.com/documentation/bunq-as-a-service/chapter-6-cards.md).
# Chapter 6: Cards
The Cards API lets you order, manage, and monitor payment cards on behalf of your users. It covers the full lifecycle — from ordering a physical or virtual card, through activation and day-to-day management (limits, status, PIN), to reading transactions and handling strong customer authentication.
All card data is sensitive, so **every card request and response is end-to-end encrypted**. Before calling any endpoint in this chapter, make sure you've set up encryption as described in the [Encryption](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#encryption) section below.
### Card types
Two card products can be ordered through the API:
| Type | Endpoint | Description |
| ---------- | ------------- | --------------------------------------------------------------------------- |
| **Debit** | `card-debit` | A Mastercard or Maestro debit card linked to one or more monetary accounts. |
| **Credit** | `card-credit` | A co-branded Mastercard credit card. |
Both are ordered per user and can be issued as a **physical** card (delivered by post) or a **virtual** card (available immediately for online use), controlled by the `order_status` field at creation.
Once created, both card types are read and updated through the shared `card` endpoint. Responses are wrapped under `CardCredit` or `CardDebit` depending on the concrete card type.
\
What you can do
* **Order cards** — create debit and credit cards, choose physical or virtual delivery, set the name and text lines, and connect them to a monetary account.
* **Manage cards** — activate a received card, change its status (deactivate, report lost/stolen, cancel), update spending and ATM limits, set the PIN, and adjust country permissions.
* **Retrieve card numbers** — generate the primary account number (PAN) and request a CVC2 code for online use.
* **Monitor transactions** — list and read card transactions (Mastercard actions) per monetary account, including amounts, merchant details, and authorisation status.
* **Handle authentication** — respond to Mastercard Identity Check (3-D Secure) challenge requests to approve or reject online purchases.
### Sections in this chapter
* [**Encryption**](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#encryption) — how to encrypt card requests and decrypt card responses. Required for all card endpoints.
* [**Create endpoints**](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#create-endpoints) — order and manage debit and credit cards.
* [**PAN endpoints**](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#pan-endpoints) — generate the primary account number (PAN) and CVC2 code.
* [**Apple/Google Pay endpoints**](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#applegoogle-pay-endpoints) — provision cards into mobile wallets.
* [**3DS and mastercard-action listing**](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#3ds-and-mastercard-action-listing) — read card transactions and handle Mastercard Identity Check challenges, including the `MASTERCARD_IDENTITY_CHECK` webhook.
### A note on authentication and webhooks
Some card flows are asynchronous. In particular, an online purchase may trigger a **Mastercard Identity Check** challenge that the user must approve or reject. bunq notifies you of these via the `MASTERCARD_IDENTITY_CHECK` webhook category; you then act on the challenge through the `challenge-request` endpoint. See [3DS and mastercard-action listing](http://localhost:63342/markdownPreview/696470241/markdown-preview-index-1953046680.html?_ijt=3ibhjgnmfho9e4g77enqdptuej#3ds-and-mastercard-action-listing) for the full flow.
***
### Encryption
Card endpoints handle sensitive data — card numbers, PINs, and CVC2 codes — so every request and response in this chapter is end-to-end encrypted. This section explains how to encrypt the payloads you send and decrypt the ones you receive. Set this up once before using any other card endpoint; calls that skip encryption will be rejected.
***
### Create endpoints
Order and manage debit and credit cards. Use `card-debit` and `card-credit` to order a new card — physical or virtual — for a user, then use the shared `card` endpoint to read a card, list all of a user's cards, and update it: activate it on delivery, change its status, adjust spending and ATM limits, set the PIN, or update country permissions. Read and update responses are returned under the `CardCredit` or `CardDebit` wrapper matching the card's type.
***
### PAN endpoints
Retrieve the sensitive card numbers needed to use a card online. Use `primary-account-number` to generate the card's PAN, and `generated-cvc2` to generate and read a CVC2 code. Both are sub-resources of a card (scoped under `card/{cardId}`) and, like everything in this chapter, are encrypted end to end.
***
### Apple/Google Pay endpoints
Provision a user's card into a mobile wallet (Apple Pay or Google Pay). These endpoints return the tokenized card data the wallet needs to complete provisioning.
***
### 3DS and Card Payments listing
Monitor card activity and handle strong customer authentication. Use `mastercard-action` to list and read a monetary account's card transactions, including amounts, merchant details, authorisation status, and the 3DS authentication status of each transaction.
Online purchases may trigger a **Mastercard Identity Check** (3-D Secure) challenge that the user must approve or reject. bunq notifies you of these through the `MASTERCARD_IDENTITY_CHECK` webhook category (event types `MASTERCARD_IDENTITY_CHECK_CHALLENGE_CREATED`, `_REJECTED`, `_FAILED`, and `_EXPIRED`). When you receive a challenge, respond to it with the `challenge-request` endpoint: read the challenge details with `GET`, then approve or reject it with `PUT` by setting `status` to `ACCEPTED_PENDING_RESPONSE` or `REJECTED_PENDING_RESPONSE`.