Business API
- GETList cards
- GETList card appearances
- POSTCreate a card
- POSTBulk create cards
- GETRetrieve a card iframe url
- PUTReport a physical card as lost
- PUTReport a physical card as stolen
- PUTDiscard a virtual card
- PUTLock a card
- PUTUnlock a card
- PATCHUpdate a card's limits
- PATCHUpdate a card's nickname
- PATCHUpdate a card's options
- PATCHUpdate a card's restrictions
- GET
Onboarding API
curl --request POST \
--url https://thirdparty.qonto.com/v2/cards/bulk \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cards": [
{
"card": {
"ship_to_business": false,
"atm_monthly_limit": 1000,
"atm_daily_limit_option": true,
"atm_daily_limit": 1000,
"payment_monthly_limit": 1000,
"holder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_level": "standard",
"atm_option": true,
"nfc_option": true,
"foreign_option": true,
"online_option": true,
"payment_daily_limit_option": true,
"payment_daily_limit": 1000,
"payment_transaction_limit_option": true,
"payment_transaction_limit": 1000,
"active_days": [
1,
3,
5
],
"address": {
"contact_name": null,
"first_line": "751 Metz Falls",
"second_line": "835",
"third_line": "Apt. 734",
"zipcode": "13563-3709",
"city": "Reinholdchester",
"country": "KI"
},
"categories": [
"transport",
"restaurant_and_bar",
"food_and_grocery"
],
"card_design": "standard.recycled.plastic.2023",
"type_of_print": "embossed"
}
}
]
}
'{
"cards": [
{
"card": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"nickname": "💳 for 🍗",
"embossed_name": "DOLORES KOULECHOV",
"status": "pending",
"pin_set": true,
"mask_pan": "511768******7662",
"exp_month": "3",
"exp_year": "2024",
"last_activity_at": "2023-11-07T05:31:56Z",
"last_digits": "7662",
"ship_to_business": false,
"atm_option": true,
"nfc_option": true,
"online_option": true,
"foreign_option": true,
"atm_monthly_limit": 1000,
"atm_monthly_spent": 1000,
"atm_daily_limit": 1000,
"atm_daily_spent": 0,
"atm_daily_limit_option": true,
"payment_monthly_limit": 1000,
"payment_monthly_spent": 1000,
"payment_daily_limit": 1000,
"payment_daily_spent": 1000,
"payment_daily_limit_option": true,
"payment_transaction_limit": 1000,
"payment_transaction_limit_option": true,
"active_days": [
1,
3,
5
],
"holder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"shipped_at": null,
"card_type": "debit",
"card_level": "standard",
"payment_lifespan_limit": 100,
"payment_lifespan_spent": 42,
"pre_expires_at": "2023-11-07T05:31:56Z",
"categories": [
"transport",
"restaurant_and_bar",
"food_and_grocery"
],
"renewed": false,
"renewal": false,
"parent_card_summary": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_digits": "7662"
},
"had_operation": false,
"had_pin_operation": false,
"card_design": "standard.recycled.plastic.2023",
"type_of_print": "embossed",
"upsold": false,
"upsell": false,
"discard_on": "2022-11-31",
"reordered": false,
"appearance": {
"assets": {
"front_large": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_large.png",
"front_small": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small.png",
"front_small_wallet": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small_wallet.png"
},
"theme": "dark",
"gradient_hex_color": "#000000"
},
"has_only_user_liftable_locks": true
}
}
]
}Bulk create cards
OAuth scope: card.write
This operation requires Strong Customer Authentication.
Creates multiple cards for the authenticated organization.
This endpoint is still in beta. Please get in touch with our team if you have any question or feedback: here.
curl --request POST \
--url https://thirdparty.qonto.com/v2/cards/bulk \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"cards": [
{
"card": {
"ship_to_business": false,
"atm_monthly_limit": 1000,
"atm_daily_limit_option": true,
"atm_daily_limit": 1000,
"payment_monthly_limit": 1000,
"holder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"card_level": "standard",
"atm_option": true,
"nfc_option": true,
"foreign_option": true,
"online_option": true,
"payment_daily_limit_option": true,
"payment_daily_limit": 1000,
"payment_transaction_limit_option": true,
"payment_transaction_limit": 1000,
"active_days": [
1,
3,
5
],
"address": {
"contact_name": null,
"first_line": "751 Metz Falls",
"second_line": "835",
"third_line": "Apt. 734",
"zipcode": "13563-3709",
"city": "Reinholdchester",
"country": "KI"
},
"categories": [
"transport",
"restaurant_and_bar",
"food_and_grocery"
],
"card_design": "standard.recycled.plastic.2023",
"type_of_print": "embossed"
}
}
]
}
'{
"cards": [
{
"card": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"nickname": "💳 for 🍗",
"embossed_name": "DOLORES KOULECHOV",
"status": "pending",
"pin_set": true,
"mask_pan": "511768******7662",
"exp_month": "3",
"exp_year": "2024",
"last_activity_at": "2023-11-07T05:31:56Z",
"last_digits": "7662",
"ship_to_business": false,
"atm_option": true,
"nfc_option": true,
"online_option": true,
"foreign_option": true,
"atm_monthly_limit": 1000,
"atm_monthly_spent": 1000,
"atm_daily_limit": 1000,
"atm_daily_spent": 0,
"atm_daily_limit_option": true,
"payment_monthly_limit": 1000,
"payment_monthly_spent": 1000,
"payment_daily_limit": 1000,
"payment_daily_spent": 1000,
"payment_daily_limit_option": true,
"payment_transaction_limit": 1000,
"payment_transaction_limit_option": true,
"active_days": [
1,
3,
5
],
"holder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"updated_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"shipped_at": null,
"card_type": "debit",
"card_level": "standard",
"payment_lifespan_limit": 100,
"payment_lifespan_spent": 42,
"pre_expires_at": "2023-11-07T05:31:56Z",
"categories": [
"transport",
"restaurant_and_bar",
"food_and_grocery"
],
"renewed": false,
"renewal": false,
"parent_card_summary": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"last_digits": "7662"
},
"had_operation": false,
"had_pin_operation": false,
"card_design": "standard.recycled.plastic.2023",
"type_of_print": "embossed",
"upsold": false,
"upsell": false,
"discard_on": "2022-11-31",
"reordered": false,
"appearance": {
"assets": {
"front_large": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_large.png",
"front_small": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small.png",
"front_small_wallet": "https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small_wallet.png"
},
"theme": "dark",
"gradient_hex_color": "#000000"
},
"has_only_user_liftable_locks": true
}
}
]
}Authorizations
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
Required only for Sandbox API requests; to get one, please sign up to the Developer Portal.
Body
1 - 50 elements- CreatePhysicalCard
- CreateVirtualCard
- CreateFlashCard
- CreateAdvertisingCard
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Whether the card is shipped to the business location, which is the organisation address as registered in Qonto.
false
Total of ATM limit per month (unit: euro). If atm_option is false, this can be omitted
10 <= x <= 30001000
Flag indicating whether the total amount per day limit should be applied to atm withdrawals. If atm_option is false, this can be omitted
true
Total of withdrawal limit per day. If atm_option and atm_daily_limit_option are false, this can be omitted
10 <= x <= 30001000
Total of payment limit by month (unit: euro).
0 <= x <= 2000001000
The membership identifier of the card holder.
The membership identifier of the card holder.
The ID of the organization the card belongs to.
The id of the bank account to which the card is attached
standard, plus, metal Flag indicating whether the card could withdraw money on an ATM.
true
Flag indicating whether the card could make a payment with NFC mode (contactless).
true
Flag indicating whether the card could make a payment outside of France.
true
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.
true
Flag indicating whether the total amount per day limit should be applied to payments
true
Total of payment limit per day.
0 <= x <= 600001000
Flag indicating whether the total amount per transaction limit should be applied to payments
true
Total of payment limit per transaction.
1000
Days card is active i.e. [1-7]. ISO8601: starts on Monday with 1.
1, 2, 3, 4, 5, 6, 7 [1, 3, 5]Address used for the delivery of the card if not shipping to the business address
{
"contact_name": null,
"first_line": "751 Metz Falls",
"second_line": "835",
"third_line": "Apt. 734",
"zipcode": "13563-3709",
"city": "Reinholdchester",
"country": "KI"
}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
[
"transport",
"restaurant_and_bar",
"food_and_grocery"
]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.
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 "standard.recycled.plastic.2023"
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.
print, embossed, "embossed"
Response
Returns the card creation result, in the same order as provided in the request.
A representation of a card, wrapped in a card property
- Option 1
- Errors
Show child attributes
Show child attributes
A representation of a card
Show child attributes
Show child attributes
Unique card identifier
Display name for the card.
1 - 40"💳 for 🍗"
String representing the name printed on the physical card object.
"DOLORES KOULECHOV"
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.
pending, live, paused, stolen, lost, pin_blocked, discarded, expired, shipped_lost, onhold, order_canceled, pre_expired, abusive "pending"
Whether the pin code for the card is set or not.
true
String representing the masked PAN of card.
"511768******7662"
The expiration month. [1-12]
"3"
The expiration year.
"2024"
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.
The last 4 numbers of the card.
"7662"
Whether the card is shipped to the business location, which is the organisation address as registered in Qonto.
false
Flag indicating whether the card could withdraw money on an ATM.
true
Flag indicating whether the card could make a payment with NFC mode (contactless).
true
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.
true
Flag indicating whether the card could make a payment outside of France.
true
Total of ATM limit per month (unit: euro).
10 <= x <= 30001000
Total of ATM spend on the current month (unit: euro).
1000
Total of withdrawal limit per day. (unit: euro)
10 <= x <= 30001000
Total of ATM spend today (unit: euro).
0
Flag indicating whether the total amount per day limit should be applied to atm withdrawals
true
Total of payment limit by month (unit: euro).
0 <= x <= 2000001000
Total of payment spend on the current month (unit: euro).
1000
Total of payment limit per day.
0 <= x <= 600001000
Total amount spent on the current day (unit: euro).
1000
Flag indicating whether the total amount per day limit should be applied to payments
true
Total of payment limit per transaction.
1000
Flag indicating whether the total amount per transaction limit should be applied to payments
true
Days card is active i.e. [1-7]. ISO8601: starts on Monday with 1.
1, 2, 3, 4, 5, 6, 7 [1, 3, 5]The membership identifier of the card holder.
The membership identifier for the initiator of the card order.
The id of the bank account to which the card is attached
The ID of the organization the card belongs to.
Datetime at which the object was last updated.
Datetime at which the object was created.
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.
null
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.
debit, prepaid "debit"
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.
standard, plus, metal, virtual, virtual_partner, flash, advertising "standard"
Total of payment limit until card expires (unit: euro). Applicable only for Flash cards.
5 <= x <= 20000Total amount spent on the card since its creation (unit: euro).
42
Flash card will be valid until this date.
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
[
"transport",
"restaurant_and_bar",
"food_and_grocery"
]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
false
Flag indicating whether the card is a renewal card
false
Flag indicating whether the card has had any operations. Operations means any attempt at usage of the card.
false
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.
false
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.
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 "standard.recycled.plastic.2023"
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.
print, embossed, "embossed"
Flag indicating whether the card has been upsold
false
Flag indicating whether the card is an upsell child card
false
Datetime at which the card will be discarded after being upsold. (upsold_at + 30 days)
"2022-11-31"
Describes if the card has been reordered and there is a new card instead.
false
Describe the visual of the card
Show child attributes
Show child attributes
Show child attributes
Show child attributes
URL to a large image of the front of the card
"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_large.png"
URL to a small image of the front of the card
"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small.png"
URL to a small image of the front of the card, optimized for wallet apps
"https://qonto.com/card-designs/standard/standard.recycled.plastic.2023/front_small_wallet.png"
Name of the theme used for the card design
dark, light "dark"
Hexadecimal color code representing the gradient color of the card design
"#000000"
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.
Was this page helpful?