List cards

Authorizations

Authorization

string

header

required

Bearer authorization header: Bearer <token>, where <token> is the access token received from the authorization server at the end of the OAuth 2.0 flow.

Headers

X-Qonto-Staging-Token

string

Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.

Query Parameters

query

string

Text search can be performed on the following fields:

memberships.first_name
memberships.last_name
cards.id
cards.nickname
cards.last_digits
cards.status
cards.pre_expires_at
cards.exp_year
cards.exp_month

page

integer

default:1

Returned page (cf. Pagination).

Example:

2

per_page

integer

default:100

Number of cards per page (cf. Pagination).

Required range: x <= 100

Example:

20

sort_by

string<property:order>

default:status:asc

Cards can be sorted by a specific property and order. Property: status, nickname, last_activity_at or created_at Order: asc (Ascending) / desc (Descending)

holder_ids[]

string<uuid>[]

Cards can be filtered by their holder_id.

The membership identifier of the card holder.

statuses[]

enum<string>[]

Cards can be filtered by their status.

Status of the card. Pending: the card is awaiting PIN to be set or issuing to complete. Live: the card is active and can be used. Paused: the card is paused and cannot be used until un-paused. Stolen: the card has been reported as stolen and cannot be used. Lost: the card has been reported as lost and cannot be used. Pin_blocked: the card has been blocked due to too many wrong PIN attempts. It can still be used for card-not-present transactions. Discarded: the card has been discarded and cannot be used. Expired: the card has expired and cannot be used. Shipped_lost: the card has been lost during shipping and cannot be used. Onhold: the card issuing is on hold due to missing KYC/KYB validation and cannot be used. Order_canceled: the card order has been canceled. Pre_expired: the flash card has reached the end of its validity and cannot be used. Abusive: the card has been reported as abusive and cannot be used.

Available options:

pending,

live,

paused,

stolen,

lost,

pin_blocked,

discarded,

expired,

shipped_lost,

onhold,

order_canceled,

pre_expired,

abusive

Example:

"statuses[]=pending&statuses[]=live"

bank_account_ids[]

string<uuid>[]

Cards can be filtered by their bank_account_id.

The id of the bank account to which the card is attached

Example:

"bank_account_ids[]=id1&bank_account_ids[]=id2"

card_levels[]

enum<string>[]

Cards can be filtered by their card_level.

Level of the card. A level defines a set of card capabilities and pricing. Standard, plus and metal are physical cards. See our Qonto cards: https://qonto.com/en/payment-methods/card.

Available options:

standard,

plus,

metal,

virtual,

virtual_partner,

flash,

advertising

Example:

"card_levels[]=virtual&card_levels[]=flash"

ids[]

string<uuid>[]

Cards can be filtered by their id.

Unique card identifier

Example:

"ids[]=id1&ids[]=id2"

Response

Returns the list of cards.

meta

object

Metadata for paginated responses

Show child attributes

meta.current_page

integer

required

The current page number

Example:

2

meta.next_page

integer

required

The next page number (null if on last page)

Example:

3

meta.prev_page

integer

required

The previous page number (null if on first page)

Example:

1

meta.total_pages

integer

required

Total number of pages

Example:

11

meta.total_count

integer

required

Total number of items across all pages

Example:

210

meta.per_page

integer

required

Number of items per page

Example:

20

cards

object[]

Show child attributes

cards.id

string<uuid>

Unique card identifier

cards.nickname

string

Display name for the card.

Required string length: 1 - 40

Example:

"💳 for 🍗"

cards.embossed_name

string | null

String representing the name printed on the physical card object.

Example:

"DOLORES KOULECHOV"

cards.status

enum<string>

Available options:

pending,

live,

paused,

stolen,

lost,

pin_blocked,

discarded,

expired,

shipped_lost,

onhold,

order_canceled,

pre_expired,

abusive

Example:

"pending"

cards.pin_set

boolean

Whether the pin code for the card is set or not.

Example:

true

cards.mask_pan

string | null

String representing the masked PAN of card.

Example:

"511768******7662"

cards.exp_month

string<number> | null

The expiration month. [1-12]

Example:

"3"

cards.exp_year

string<number> | null

The expiration year.

Example:

"2024"

cards.last_activity_at

string<date-time>

The datetime of the last activity happened with this card. By activity we mean any attempt to use the cards, successful or not. Creating a transaction or not. Does not include any updates to settings or options.

cards.last_digits

string<^\d\d\d\d$> | null

The last 4 numbers of the card.

Example:

"7662"

cards.ship_to_business

boolean

Whether the card is shipped to the business location, which is the organisation address as registered in Qonto.

Example:

false

cards.atm_option

boolean

Flag indicating whether the card could withdraw money on an ATM.

Example:

true

cards.nfc_option

boolean

Flag indicating whether the card could make a payment with NFC mode (contactless).

Example:

true

cards.online_option

boolean

Flag indicating whether the card could make an online payment. Online payment are not related to any mastercard registered Point of Sale or terminal of payment.

Example:

true

cards.foreign_option

boolean

Flag indicating whether the card could make a payment outside of France.

Example:

true

cards.atm_monthly_limit

integer

Total of ATM limit per month (unit: euro).

Required range: 10 <= x <= 3000

Example:

1000

cards.atm_monthly_spent

number

Total of ATM spend on the current month (unit: euro).

Example:

1000

cards.atm_daily_limit

integer

Total of withdrawal limit per day. (unit: euro)

Required range: 10 <= x <= 3000

Example:

1000

cards.atm_daily_spent

number

Total of ATM spend today (unit: euro).

Example:

0

cards.atm_daily_limit_option

boolean

Flag indicating whether the total amount per day limit should be applied to atm withdrawals

Example:

true

cards.payment_monthly_limit

integer

Total of payment limit by month (unit: euro).

Required range: 0 <= x <= 200000

Example:

1000

cards.payment_monthly_spent

number

Total of payment spend on the current month (unit: euro).

Example:

1000

cards.payment_daily_limit

integer

Total of payment limit per day.

Required range: 0 <= x <= 60000

Example:

1000

cards.payment_daily_spent

number

Total amount spent on the current day (unit: euro).

Example:

1000

cards.payment_daily_limit_option

boolean

Flag indicating whether the total amount per day limit should be applied to payments

Example:

true

cards.payment_transaction_limit

integer

Total of payment limit per transaction.

Example:

1000

cards.payment_transaction_limit_option

boolean

Flag indicating whether the total amount per transaction limit should be applied to payments

Example:

true

cards.active_days

enum<integer>[]

Days card is active i.e. [1-7]. ISO8601: starts on Monday with 1.

Available options:

1,

2,

3,

4,

5,

6,

7

Example:

[1, 3, 5]

cards.holder_id

string<uuid>

The membership identifier of the card holder.

cards.initiator_id

string<uuid>

The membership identifier for the initiator of the card order.

cards.bank_account_id

string<uuid>

The id of the bank account to which the card is attached

cards.organization_id

string<uuid>

The ID of the organization the card belongs to.

cards.updated_at

string<date-time>

Datetime at which the object was last updated.

cards.created_at

string<date-time>

Datetime at which the object was created.

cards.shipped_at

string<date-time> | null

For physical cards only, Datetime at which the card was shipped to its holder. Depending on the carrier (local or international), delivery can take from 2 to 5 business days to complete the reception of the card.

Example:

null

cards.card_type

enum<string>

Type of the card. Currently only debit cards are supported. It has an impact on when the money is debited but also in the acceptance on the merchant side.

Available options:

debit,

prepaid

Example:

"debit"

cards.card_level

enum<string>

Level of the card. A level defines a set of card capabilities and pricing. Standard, plus and metal are physical cards. See our Qonto cards: https://qonto.com/en/payment-methods/card.

Available options:

standard,

plus,

metal,

virtual,

virtual_partner,

flash,

advertising

Example:

"standard"

cards.payment_lifespan_limit

integer

default:100

Total of payment limit until card expires (unit: euro). Applicable only for Flash cards.

Required range: 5 <= x <= 20000

cards.payment_lifespan_spent

number

Total amount spent on the card since its creation (unit: euro).

Example:

42

cards.pre_expires_at

string<date-time> | null

Flash card will be valid until this date.

cards.categories

string[]

By default it's empty array - []. If it's empty array - [] means that category restrictions are turned off and all the categories are allowed. Can be set to not empty only for organizations with price plan starting from Team.

List of allowed category tags:

transport
restaurant_and_bar
food_and_grocery
it_and_electronics
utility
tax
legal_and_accounting
atm
office_supply
hardware_and_equipment
finance

Example:

[
  "transport",
  "restaurant_and_bar",
  "food_and_grocery"
]

cards.renewed

boolean

Flag indicating whether the expiring card has been renewed e.i. if renewal card has been created then the expiring card's renewed field becomes true

Example:

false

cards.renewal

boolean

Flag indicating whether the card is a renewal card

Example:

false

cards.parent_card_summary

object

Summary of this card's parent (the card which this card is a renewal of)

Show child attributes

cards.parent_card_summary.id

string<uuid>

Unique card identifier

cards.parent_card_summary.last_digits

string<^\d\d\d\d$> | null

The last 4 numbers of the card.

Example:

"7662"

cards.had_operation

boolean

Flag indicating whether the card has had any operations. Operations means any attempt at usage of the card.

Example:

false

cards.had_pin_operation

boolean

Flag indicating whether the card is PIN activated through a PIN operation or not. PIN operations means any attempt to use the card that requires its PIN code.

Example:

false

cards.card_design

enum<string>

The visuals for the card are specified according to the card level. For example, "standard.recycled.plastic.2023" is available only for the standard design level, while "plus.recycled.plastic.lilac.2023" is available only for the plus design level. You can determine the design available for a specific card level by looking at the prefix of the card design.

Available options:

standard.recycled.plastic.2023,

plus.recycled.plastic.silver.2023,

plus.recycled.plastic.black.2023,

plus.recycled.plastic.lilac.2023,

metal.graphite.black.2019,

metal.mineral.gray.2024,

metal.sand.gold.2024,

virtual.default.2017,

virtual.blueberry.2025,

virtual.sakura.2025,

virtual.plum.2025,

virtual.dawn.2025,

virtual.together.or.nothing.2025,

virtual.gus.gus.2025,

virtual.forever.bound.2025,

virtual.puzzle.2025,

flash.default.2021,

advertising.default.2023

Example:

"standard.recycled.plastic.2023"

cards.type_of_print

enum<string> | null

Specifies how the card information is presented on the physical card. This property is exclusively available for plus cards; other card levels must omit the value.

Available options:

print,

embossed,

Example:

"embossed"

cards.upsold

boolean

Flag indicating whether the card has been upsold

Example:

false

cards.upsell

boolean

Flag indicating whether the card is an upsell child card

Example:

false

cards.discard_on

string<^[0-9]{4,}-[0-9]{2}-[0-9]{2}$> | null

Datetime at which the card will be discarded after being upsold. (upsold_at + 30 days)

Example:

"2022-11-31"

cards.reordered

boolean

default:false

Describes if the card has been reordered and there is a new card instead.

Example:

false

cards.appearance

object

Describe the visual of the card

Show child attributes

cards.appearance.assets

object

required

Show child attributes

cards.appearance.assets.front_large

string<uri>

required

URL to a large image of the front of the card

Example:

"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_large.png"

cards.appearance.assets.front_small

string<uri>

required

URL to a small image of the front of the card

Example:

"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small.png"

cards.appearance.assets.front_small_wallet

string<uri>

required

URL to a small image of the front of the card, optimized for wallet apps

Example:

"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small_wallet.png"

cards.appearance.theme

enum<string>

required

Name of the theme used for the card design

Available options:

dark,

light

Example:

"dark"

cards.appearance.gradient_hex_color

string

Hexadecimal color code representing the gradient color of the card design

Example:

"#000000"

cards.has_only_user_liftable_locks

boolean

For a card in the paused status, it represents whether the card can be unlocked by the user. If the value is set to false, it means that the card may be locked for reasons that are not user-determined, for example the organization being suspended.

Business API

Onboarding API

Authorizations

Headers

Query Parameters

Response