> 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/create-update-list-cards.md).
# Create/Update/List Cards
## Create Credit Card
> 🔒 \*\*Encrypted endpoint\*\* — the request body and response are end-to-end encrypted. See the Encryption section.\
> \
> Order a new credit card that can be connected to monetary accounts.
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Card Management","description":"Credit and debit card creation and management"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}},"BunqClientEncryptionIv":{"name":"X-Bunq-Client-Encryption-Iv","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded 16-byte AES initialization vector.\n","schema":{"type":"string"}},"BunqClientEncryptionKey":{"name":"X-Bunq-Client-Encryption-Key","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded, RSA-encrypted AES key.\n","schema":{"type":"string"}},"BunqClientEncryptionHmac":{"name":"X-Bunq-Client-Encryption-Hmac","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded HMAC-SHA1 of the IV concatenated with the ciphertext.\n","schema":{"type":"string"}}},"schemas":{"Card":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"public_uuid":{"type":"string"},"type":{"type":"string","enum":["MASTERCARD"]},"sub_type":{"type":"string"},"product_type":{"type":"string"},"product_sub_type":{"type":"string"},"first_line":{"type":"string"},"second_line":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED","EXPIRED","PIN_TRIES_EXCEEDED"]},"sub_status":{"type":"string"},"order_status":{"type":"string"},"expected_delivery_date":{"type":"string","format":"date"},"expiry_date":{"type":"string","format":"date"},"name_on_card":{"type":"string"},"user_id":{"type":"integer","description":"DEPRECATED. ID of the user who owns the card."},"user_owner_id":{"type":"integer"},"user_holder_id":{"type":"integer"},"card_limit":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"card_limit_atm":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"setting":{"type":"object","properties":{"currency_routing_type":{"type":"string"},"image_id":{"type":"integer","nullable":true},"service_id":{"type":"integer","nullable":true},"color":{"type":"string"},"icon":{"type":"string"}}},"pin_code_assignment":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"monetary_account_id":{"type":"integer"},"status":{"type":"string"},"routing_type":{"type":"string"}}}},"country":{"type":"string"},"country_permission":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"}}}},"primary_account_numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"description":{"type":"string"},"four_digit":{"type":"string"},"type":{"type":"string"}}}},"payment_account_reference":{"type":"string"},"monetary_account_id_fallback":{"type":"integer","nullable":true},"monetary_account":{"type":"object","nullable":true,"description":"Current monetary account (only for prepaid credit cards)."},"is_card_eligible_for_free_replacement":{"type":"boolean"},"is_limited_edition":{"type":"boolean"},"is_card_frozen_payment_tokenized_allowed":{"type":"boolean"},"card_generated_cvc2":{"type":"object","nullable":true,"properties":{"CardGeneratedCvc2":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"cvc2":{"type":"string"},"status":{"type":"string"},"expiry_time":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string"}}}}}}}}},"paths":{"/user/{userId}/card-credit":{"post":{"tags":["Card Management"],"summary":"Create Credit Card","description":"🔒 **Encrypted endpoint** — the request body and response are end-to-end encrypted. See the Encryption section.\n\nOrder a new credit card that can be connected to monetary accounts.\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"},{"$ref":"#/components/parameters/BunqClientEncryptionIv"},{"$ref":"#/components/parameters/BunqClientEncryptionKey"},{"$ref":"#/components/parameters/BunqClientEncryptionHmac"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["second_line","type","product_type"],"properties":{"first_line":{"type":"string","description":"First line of text on card (max 17 characters)"},"second_line":{"type":"string","description":"Second line of text on card (max 17 characters)"},"name_on_card":{"type":"string","description":"User's name as it will appear on the card"},"preferred_name_on_card":{"type":"string","description":"User's preferred name for the card"},"type":{"type":"string","enum":["MASTERCARD"],"description":"Card network type - currently only MASTERCARD is supported"},"product_type":{"type":"string","enum":["MASTERCARD_CREDIT_CO_BRANDED","MASTERCARD_BUSINESS_CO_BRANDED"],"description":"The product type of the card to order."},"product_sub_type":{"type":"string","enum":["PARTNER_UNIQUE_ENUM"],"description":"Indicates the sub_type of the product. Responsible for the card design (physical or in the Wallet)"},"country":{"type":"string","description":"Country domestic to the card (ISO-3166). Defaults to country of residence of user."},"order_status":{"type":"string","enum":["NEW_CARD_REQUEST_RECEIVED","VIRTUAL_DELIVERY"],"description":"Card delivery status:\n- `NEW_CARD_REQUEST_RECEIVED`: Physical card will be delivered by post\n- `VIRTUAL_DELIVERY`: Virtual card for immediate online use\n"}}}}}},"responses":{"200":{"description":"Credit card created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"type":"object","properties":{"CardCredit":{"$ref":"#/components/schemas/Card"}}}}}}}}}}}}}}
```
## Create Debit Card
> 🔒 \*\*Encrypted endpoint\*\* — the request body and response are end-to-end encrypted. See the Encryption section.\
> \
> Order a new debit card that can be connected to monetary accounts.\
> \
> \*\*Available Card Types:\*\*\
> \- \`MASTERCARD\`: Mastercard debit card
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Card Management","description":"Credit and debit card creation and management"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}},"BunqClientEncryptionIv":{"name":"X-Bunq-Client-Encryption-Iv","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded 16-byte AES initialization vector.\n","schema":{"type":"string"}},"BunqClientEncryptionKey":{"name":"X-Bunq-Client-Encryption-Key","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded, RSA-encrypted AES key.\n","schema":{"type":"string"}},"BunqClientEncryptionHmac":{"name":"X-Bunq-Client-Encryption-Hmac","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded HMAC-SHA1 of the IV concatenated with the ciphertext.\n","schema":{"type":"string"}}},"schemas":{"Card":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"public_uuid":{"type":"string"},"type":{"type":"string","enum":["MASTERCARD"]},"sub_type":{"type":"string"},"product_type":{"type":"string"},"product_sub_type":{"type":"string"},"first_line":{"type":"string"},"second_line":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED","EXPIRED","PIN_TRIES_EXCEEDED"]},"sub_status":{"type":"string"},"order_status":{"type":"string"},"expected_delivery_date":{"type":"string","format":"date"},"expiry_date":{"type":"string","format":"date"},"name_on_card":{"type":"string"},"user_id":{"type":"integer","description":"DEPRECATED. ID of the user who owns the card."},"user_owner_id":{"type":"integer"},"user_holder_id":{"type":"integer"},"card_limit":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"card_limit_atm":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"setting":{"type":"object","properties":{"currency_routing_type":{"type":"string"},"image_id":{"type":"integer","nullable":true},"service_id":{"type":"integer","nullable":true},"color":{"type":"string"},"icon":{"type":"string"}}},"pin_code_assignment":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"monetary_account_id":{"type":"integer"},"status":{"type":"string"},"routing_type":{"type":"string"}}}},"country":{"type":"string"},"country_permission":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"}}}},"primary_account_numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"description":{"type":"string"},"four_digit":{"type":"string"},"type":{"type":"string"}}}},"payment_account_reference":{"type":"string"},"monetary_account_id_fallback":{"type":"integer","nullable":true},"monetary_account":{"type":"object","nullable":true,"description":"Current monetary account (only for prepaid credit cards)."},"is_card_eligible_for_free_replacement":{"type":"boolean"},"is_limited_edition":{"type":"boolean"},"is_card_frozen_payment_tokenized_allowed":{"type":"boolean"},"card_generated_cvc2":{"type":"object","nullable":true,"properties":{"CardGeneratedCvc2":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"cvc2":{"type":"string"},"status":{"type":"string"},"expiry_time":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string"}}}}}}}}},"paths":{"/user/{userId}/card-debit":{"post":{"tags":["Card Management"],"summary":"Create Debit Card","description":"🔒 **Encrypted endpoint** — the request body and response are end-to-end encrypted. See the Encryption section.\n\nOrder a new debit card that can be connected to monetary accounts.\n\n**Available Card Types:**\n- `MASTERCARD`: Mastercard debit card\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"},{"$ref":"#/components/parameters/BunqClientEncryptionIv"},{"$ref":"#/components/parameters/BunqClientEncryptionKey"},{"$ref":"#/components/parameters/BunqClientEncryptionHmac"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["second_line","type","product_type"],"properties":{"second_line":{"type":"string","description":"Second line of text on the card (max 17 characters)"},"name_on_card":{"type":"string","description":"User's name as it will appear on the card"},"preferred_name_on_card":{"type":"string","description":"User's preferred name for the card"},"type":{"type":"string","enum":["MASTERCARD"],"description":"Card network type:\n- `MASTERCARD`: Mastercard debit card\n"},"product_type":{"type":"string","description":"The product type of the debit card to order"},"product_sub_type":{"type":"string","enum":["PARTNER_UNIQUE_ENUM"],"description":"Indicates the sub_type of the product. Responsible the card design (physical or in the Wallet)"},"pin_code_assignment":{"type":"array","description":"Array of PIN assignments for the card","items":{"type":"object"}},"monetary_account_id_fallback":{"type":"integer","description":"ID of fallback account if insufficient balance"},"country":{"type":"string","description":"Country domestic to the card (ISO-3166)"},"order_status":{"type":"string","enum":["NEW_CARD_REQUEST_RECEIVED","VIRTUAL_DELIVERY"],"description":"Card delivery status:\n- `NEW_CARD_REQUEST_RECEIVED`: Physical card will be delivered by post\n- `VIRTUAL_DELIVERY`: Virtual card for immediate online use\n"},"customization_type":{"type":"string","enum":["ONLY_ICON","FREE_HAND"],"description":"Card design customization:\n- `ONLY_ICON`: Only icon customization allowed\n- `FREE_HAND`: Free-hand design customization allowed\n"}}}}}},"responses":{"200":{"description":"Debit card created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"type":"object","properties":{"CardDebit":{"$ref":"#/components/schemas/Card"}}}}}}}}}}}}}}
```
## Get Card Details
> 🔒 \*\*Encrypted endpoint\*\* — the response is end-to-end encrypted. See the Encryption section.\
> \
> Get details of a specific card.
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Card Management","description":"Credit and debit card creation and management"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}},"BunqClientEncryptionIv":{"name":"X-Bunq-Client-Encryption-Iv","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded 16-byte AES initialization vector.\n","schema":{"type":"string"}},"BunqClientEncryptionKey":{"name":"X-Bunq-Client-Encryption-Key","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded, RSA-encrypted AES key.\n","schema":{"type":"string"}},"BunqClientEncryptionHmac":{"name":"X-Bunq-Client-Encryption-Hmac","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded HMAC-SHA1 of the IV concatenated with the ciphertext.\n","schema":{"type":"string"}}},"schemas":{"Card":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"public_uuid":{"type":"string"},"type":{"type":"string","enum":["MASTERCARD"]},"sub_type":{"type":"string"},"product_type":{"type":"string"},"product_sub_type":{"type":"string"},"first_line":{"type":"string"},"second_line":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED","EXPIRED","PIN_TRIES_EXCEEDED"]},"sub_status":{"type":"string"},"order_status":{"type":"string"},"expected_delivery_date":{"type":"string","format":"date"},"expiry_date":{"type":"string","format":"date"},"name_on_card":{"type":"string"},"user_id":{"type":"integer","description":"DEPRECATED. ID of the user who owns the card."},"user_owner_id":{"type":"integer"},"user_holder_id":{"type":"integer"},"card_limit":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"card_limit_atm":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"setting":{"type":"object","properties":{"currency_routing_type":{"type":"string"},"image_id":{"type":"integer","nullable":true},"service_id":{"type":"integer","nullable":true},"color":{"type":"string"},"icon":{"type":"string"}}},"pin_code_assignment":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"monetary_account_id":{"type":"integer"},"status":{"type":"string"},"routing_type":{"type":"string"}}}},"country":{"type":"string"},"country_permission":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"}}}},"primary_account_numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"description":{"type":"string"},"four_digit":{"type":"string"},"type":{"type":"string"}}}},"payment_account_reference":{"type":"string"},"monetary_account_id_fallback":{"type":"integer","nullable":true},"monetary_account":{"type":"object","nullable":true,"description":"Current monetary account (only for prepaid credit cards)."},"is_card_eligible_for_free_replacement":{"type":"boolean"},"is_limited_edition":{"type":"boolean"},"is_card_frozen_payment_tokenized_allowed":{"type":"boolean"},"card_generated_cvc2":{"type":"object","nullable":true,"properties":{"CardGeneratedCvc2":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"cvc2":{"type":"string"},"status":{"type":"string"},"expiry_time":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string"}}}}}}}}},"paths":{"/user/{userId}/card/{cardId}":{"get":{"tags":["Card Management"],"summary":"Get Card Details","description":"🔒 **Encrypted endpoint** — the response is end-to-end encrypted. See the Encryption section.\n\nGet details of a specific card.\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"cardId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"},{"$ref":"#/components/parameters/BunqClientEncryptionIv"},{"$ref":"#/components/parameters/BunqClientEncryptionKey"},{"$ref":"#/components/parameters/BunqClientEncryptionHmac"}],"responses":{"200":{"description":"Card details","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"CardCredit":{"$ref":"#/components/schemas/Card"}}},{"type":"object","properties":{"CardDebit":{"$ref":"#/components/schemas/Card"}}}]}}}}}}}}}}}}
```
## List Cards
> 🔒 \*\*Encrypted endpoint\*\* — the response is end-to-end encrypted. See the Encryption section.\
> \
> Get all cards (credit and debit) available to the user.
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Card Management","description":"Credit and debit card creation and management"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}},"BunqClientEncryptionIv":{"name":"X-Bunq-Client-Encryption-Iv","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded 16-byte AES initialization vector.\n","schema":{"type":"string"}},"BunqClientEncryptionKey":{"name":"X-Bunq-Client-Encryption-Key","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded, RSA-encrypted AES key.\n","schema":{"type":"string"}},"BunqClientEncryptionHmac":{"name":"X-Bunq-Client-Encryption-Hmac","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded HMAC-SHA1 of the IV concatenated with the ciphertext.\n","schema":{"type":"string"}}},"schemas":{"Card":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"public_uuid":{"type":"string"},"type":{"type":"string","enum":["MASTERCARD"]},"sub_type":{"type":"string"},"product_type":{"type":"string"},"product_sub_type":{"type":"string"},"first_line":{"type":"string"},"second_line":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED","EXPIRED","PIN_TRIES_EXCEEDED"]},"sub_status":{"type":"string"},"order_status":{"type":"string"},"expected_delivery_date":{"type":"string","format":"date"},"expiry_date":{"type":"string","format":"date"},"name_on_card":{"type":"string"},"user_id":{"type":"integer","description":"DEPRECATED. ID of the user who owns the card."},"user_owner_id":{"type":"integer"},"user_holder_id":{"type":"integer"},"card_limit":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"card_limit_atm":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"setting":{"type":"object","properties":{"currency_routing_type":{"type":"string"},"image_id":{"type":"integer","nullable":true},"service_id":{"type":"integer","nullable":true},"color":{"type":"string"},"icon":{"type":"string"}}},"pin_code_assignment":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"monetary_account_id":{"type":"integer"},"status":{"type":"string"},"routing_type":{"type":"string"}}}},"country":{"type":"string"},"country_permission":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"}}}},"primary_account_numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"description":{"type":"string"},"four_digit":{"type":"string"},"type":{"type":"string"}}}},"payment_account_reference":{"type":"string"},"monetary_account_id_fallback":{"type":"integer","nullable":true},"monetary_account":{"type":"object","nullable":true,"description":"Current monetary account (only for prepaid credit cards)."},"is_card_eligible_for_free_replacement":{"type":"boolean"},"is_limited_edition":{"type":"boolean"},"is_card_frozen_payment_tokenized_allowed":{"type":"boolean"},"card_generated_cvc2":{"type":"object","nullable":true,"properties":{"CardGeneratedCvc2":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"cvc2":{"type":"string"},"status":{"type":"string"},"expiry_time":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string"}}}}}}},"Pagination":{"type":"object","properties":{"future_url":{"type":["string","null"],"description":"URL to poll for results newer than the current real-time window (useful for long-polling; null if not applicable)."},"newer_url":{"type":["string","null"],"description":"URL to fetch the next newer page relative to the current result set (null if at newest page)."},"older_url":{"type":["string","null"],"description":"URL to fetch an older page (null if none)."}}}}},"paths":{"/user/{userId}/card":{"get":{"tags":["Card Management"],"summary":"List Cards","description":"🔒 **Encrypted endpoint** — the response is end-to-end encrypted. See the Encryption section.\n\nGet all cards (credit and debit) available to the user.\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"},{"$ref":"#/components/parameters/BunqClientEncryptionIv"},{"$ref":"#/components/parameters/BunqClientEncryptionKey"},{"$ref":"#/components/parameters/BunqClientEncryptionHmac"}],"responses":{"200":{"description":"List of all user cards","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"CardCredit":{"$ref":"#/components/schemas/Card"}}},{"type":"object","properties":{"CardDebit":{"$ref":"#/components/schemas/Card"}}}]}},"Pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}}}}
```
## Update Card
> 🔒 \*\*Encrypted endpoint\*\* — the request body and response are end-to-end encrypted. See the Encryption section.\
> \
> Update card details including PIN code, status, limits, and settings.\
> Can be used to activate cards when they are received.
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Card Management","description":"Credit and debit card creation and management"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}},"BunqClientEncryptionIv":{"name":"X-Bunq-Client-Encryption-Iv","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded 16-byte AES initialization vector.\n","schema":{"type":"string"}},"BunqClientEncryptionKey":{"name":"X-Bunq-Client-Encryption-Key","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded, RSA-encrypted AES key.\n","schema":{"type":"string"}},"BunqClientEncryptionHmac":{"name":"X-Bunq-Client-Encryption-Hmac","in":"header","required":true,"description":"Encryption header (required on encrypted endpoints). Base64-encoded HMAC-SHA1 of the IV concatenated with the ciphertext.\n","schema":{"type":"string"}}},"schemas":{"Card":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"public_uuid":{"type":"string"},"type":{"type":"string","enum":["MASTERCARD"]},"sub_type":{"type":"string"},"product_type":{"type":"string"},"product_sub_type":{"type":"string"},"first_line":{"type":"string"},"second_line":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED","EXPIRED","PIN_TRIES_EXCEEDED"]},"sub_status":{"type":"string"},"order_status":{"type":"string"},"expected_delivery_date":{"type":"string","format":"date"},"expiry_date":{"type":"string","format":"date"},"name_on_card":{"type":"string"},"user_id":{"type":"integer","description":"DEPRECATED. ID of the user who owns the card."},"user_owner_id":{"type":"integer"},"user_holder_id":{"type":"integer"},"card_limit":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"card_limit_atm":{"type":"object","properties":{"currency":{"type":"string"},"value":{"type":"string"}}},"setting":{"type":"object","properties":{"currency_routing_type":{"type":"string"},"image_id":{"type":"integer","nullable":true},"service_id":{"type":"integer","nullable":true},"color":{"type":"string"},"icon":{"type":"string"}}},"pin_code_assignment":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"monetary_account_id":{"type":"integer"},"status":{"type":"string"},"routing_type":{"type":"string"}}}},"country":{"type":"string"},"country_permission":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"}}}},"primary_account_numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"uuid":{"type":"string"},"description":{"type":"string"},"four_digit":{"type":"string"},"type":{"type":"string"}}}},"payment_account_reference":{"type":"string"},"monetary_account_id_fallback":{"type":"integer","nullable":true},"monetary_account":{"type":"object","nullable":true,"description":"Current monetary account (only for prepaid credit cards)."},"is_card_eligible_for_free_replacement":{"type":"boolean"},"is_limited_edition":{"type":"boolean"},"is_card_frozen_payment_tokenized_allowed":{"type":"boolean"},"card_generated_cvc2":{"type":"object","nullable":true,"properties":{"CardGeneratedCvc2":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"cvc2":{"type":"string"},"status":{"type":"string"},"expiry_time":{"type":"string","format":"date-time","nullable":true},"type":{"type":"string"}}}}}}}}},"paths":{"/user/{userId}/card/{cardId}":{"put":{"tags":["Card Management"],"summary":"Update Card","description":"🔒 **Encrypted endpoint** — the request body and response are end-to-end encrypted. See the Encryption section.\n\nUpdate card details including PIN code, status, limits, and settings.\nCan be used to activate cards when they are received.\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"cardId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"},{"$ref":"#/components/parameters/BunqClientEncryptionIv"},{"$ref":"#/components/parameters/BunqClientEncryptionKey"},{"$ref":"#/components/parameters/BunqClientEncryptionHmac"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pin_code":{"type":"string","description":"The plaintext PIN code (requires encryption)"},"status":{"type":"string","enum":["ACTIVE","DEACTIVATED","LOST","STOLEN","CANCELLED"],"description":"Card status to set:\n- `ACTIVE`: Activate the card\n- `DEACTIVATED`: Temporarily deactivate the card\n- `LOST`: Report card as lost (permanent)\n- `STOLEN`: Report card as stolen (permanent)\n- `CANCELLED`: Cancel the card (permanent)\n"},"card_limit":{"type":"object","description":"Daily spending limit for the card","properties":{"value":{"type":"string"},"currency":{"type":"string"}}},"card_limit_atm":{"type":"object","description":"Daily ATM withdrawal limit","properties":{"value":{"type":"string"},"currency":{"type":"string"}}},"monetary_account_id_fallback":{"type":"integer","description":"ID of fallback account for insufficient balance"},"cancellation_reason":{"type":"string","enum":["FRAUD","LOST","STOLEN","OTHER"],"description":"Reason for cancelling card:\n- `FRAUD`: Fraudulent activity detected\n- `LOST`: Card has been lost\n- `STOLEN`: Card has been stolen\n- `OTHER`: Other reason\n"}}}}}},"responses":{"200":{"description":"Card updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"CardCredit":{"$ref":"#/components/schemas/Card"}}},{"type":"object","properties":{"CardDebit":{"$ref":"#/components/schemas/Card"}}}]}}}}}}}}}}}}
```