openapi: 3.0.1
info:
version: '1.0'
title: Business Accounting Cards API
description: "As a Revolut Business customer with a Business Account, you can use the Business API to automate your own business processes.\nSave time, reduce your costs, and avoid errors by using the Business API. \n\n:::tip[Before you get started]\nTo learn more about the Business API and its features, check the [**user guides**](https://developer.revolut.com/docs/guides/manage-accounts/introduction).\n\nYou can reach them at any time from the main navigation bar **→ Guides → Business**.\n:::\n\nYou can view accounts, manage counterparties, make payments or currency exchanges without manual effort in the Web UI:\n\n- Accounting: [Account management](https://developer.revolut.com/docs/api/business#get-account), [Accounting settings](https://developer.revolut.com/docs/api/business#tag-accounting), [Expense management](https://developer.revolut.com/docs/api/business#get-expense), [Transactions](https://developer.revolut.com/docs/api/business#get-transactions) \n- Payments: \n - [Counterparty management](https://developer.revolut.com/docs/api/business#get-counterparties)\n - Payment management: [Payment drafts](https://developer.revolut.com/docs/api/business#delete-payment-draft), [Payout links](https://developer.revolut.com/docs/api/business#get-payout-link), [Transfers](https://developer.revolut.com/docs/api/business#tag-transfers)\n - [Foreign exchange](https://developer.revolut.com/docs/api/business#tag-foreign-exchange)\n- Business team: [Card management](https://developer.revolut.com/docs/api/business#delete-card), [Card invitation management](https://developer.revolut.com/docs/api/business#update-card-invitation), [Team member management](https://developer.revolut.com/docs/api/business#delete-team-member)\n- Developer tools: [Sandbox simulations](https://developer.revolut.com/docs/api/business#tag-simulations), [Webhook management](https://developer.revolut.com/docs/api/business#tag-webhooks-v2)\n\nTo see the reference for the specific endpoints and operations of this API, browse the menu on the left.\n\n### Test the Business API\n\nYou can test the Business API in Postman by forking this collection:\n\n[](https://www.postman.com/revolut-api/workspace/revolut-developers/overview)"
contact: {}
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
- url: https://sandbox-b2b.revolut.com/api/1.0
description: Sandbox server (uses test data)
tags:
- name: Cards
description: 'Manage cards issued for your business, freeze, unfreeze, lock, unlock, terminate and update card settings, such as spending limits and merchant controls.
:::note
- This feature is not available in Sandbox.
- To increase your account''s card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::
For more information, see the guides: [Manage cards for your business](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards).
:::tip [Card invitations for onboarding team members]
To prepare virtual cards for team members who have not completed onboarding yet, use [Card invitations](https://developer.revolut.com/docs/api/business#update-card-invitation) instead.
:::'
paths:
/cards:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
get:
summary: Retrieve a list of cards
operationId: getCards
description: 'Get the list of all cards in your organisation.
The results are paginated and sorted by the `created_at` date in reverse chronological order.
:::note
- This feature is not available in Sandbox.
- To increase your account''s card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::
For more information, see the guides: [Manage cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards).'
security:
- AccessToken:
- READ
tags:
- Cards
parameters:
- in: query
name: created_before
schema:
type: string
format: date-time
default: the date-time at which the request is made
description: 'Retrieves cards with `created_at` < `created_before`.
The default value is the current date and time at which you are calling the endpoint.
Provided in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.'
- name: limit
in: query
required: false
description: 'The maximum number of cards to return per page.
To get to the next page, make a new request and use the `created_at` date of the last card returned in the previous response as the value for `created_before`.'
schema:
type: number
format: integer
default: 100
maximum: 100
minimum: 1
responses:
'200':
description: List of cards of the business
content:
application/json:
schema:
$ref: '#/components/schemas/CardsResponse'
examples:
list_of_cards:
$ref: '#/components/examples/cardsListSimple'
'400':
description: Bad pagination parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 2101
message: 'Parameter limit must be a valid integer in range: [1, 100].'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
summary: Create a card
operationId: createCard
description: 'Create a new [team member card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards), [company card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards), or [auto-issued card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards).
When using the API, you can create only virtual cards.
To create a physical card, use the [Revolut Business app](https://business.revolut.com).
:::note
- This feature is not available in Sandbox.
- To increase your account''s card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::
For more information, see the guides: [Manage cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards).'
security:
- AccessToken:
- WRITE
tags:
- Cards
requestBody:
description: Card to create
required: true
content:
application/json:
schema:
type: object
properties:
request_id:
type: string
description: 'A unique ID of the request that you provide.
There is no strict requirement on the format of this ID, but we suggest using v4 UUIDs.
:::warning
This ID is used to prevent duplicate card creation requests in case of a lost connection or client error, so make sure you use the same `request_id` for requests related to the same card.
The deduplication is limited to 24 hours counting from the first request using a given ID.
For more information, see the guides: [Manage cards - Idempotency](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#idempotency).
:::'
maxLength: 40
holder_id:
type: string
format: uuid
description: "The ID of the team member to assign as the holder of the card.\n\n:::tip\nTo retrieve a team member's ID, use the [`GET /team-members` operation](https://developer.revolut.com/docs/api/business#get-team-members).\n:::\n\nFor virtual cards (`virtual=true`), this field is optional. \nIf not provided, the type of the issued card depends on `contact_ids`:\n - `contact_ids` provided → [company card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards)\n - `contact_ids` not specified → [auto-issued card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards)"
contact_ids:
description: 'The list of [contacts](https://help.revolut.com/business/help/cards/more-on-cards/company-cards/) for the card.
Up to 5 team members sharing the card, much like co-holders.
Can be [edited](https://developer.revolut.com/docs/api/business#update-card-contacts).
Allowed only for [company cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) (`virtual=true`, `holder_id` not specified).'
type: array
minItems: 1
maxItems: 5
items:
type: string
format: uuid
product:
description: 'The card product offered by the card provider for this card.
In other words, the program that the card is issued under.
Provided only for virtual cards with no holder ID (`virtual=true`, and `holder_id` not specified):
- **Required** for [auto-issued cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) (`contact_ids` not specified)
- Optional for [company cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) (`contact_ids` specified)
Not allowed for [team member cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) (`holder_id` present).
:::note
This property is only available to travel intermediaries using our travel solution.
To use it, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::'
type: object
required:
- code
properties:
code:
type: string
description: The code of the card product.
example: MBJ
virtual:
type: boolean
enum:
- true
description: "Specifies the type of the card. \nMust be set to `true`, as with the API, you can create only virtual cards.\n\n:::tip\nTo create a physical card, use the [Revolut Business app](https://business.revolut.com).\n:::"
label:
type: string
description: 'The label for the issued card, displayed in the UI to help distinguish between cards.
If not specified, no label will be added.'
maxLength: 30
references:
description: "References for the card.\nUp to 5 name-value pairs assigned to the card for tracking.\n\n:::info\nEach time the card is used, the references are recorded in the [transaction details](https://developer.revolut.com/docs/api/business#get-transaction#response) (`card.references`), helping track transactions made with this card.\n:::\n\nThe names must be unique.\nThe references can be [amended](https://developer.revolut.com/docs/api/business#update-card-references) up to 10 times.\n\nReferences are only supported for cards owned by the business (i.e. [company](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) or [auto-issued cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards)).\nThey are **not** supported for [team member cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#different-types-of-cards) (i.e. with `holder_id` present). \n\n:::note\nThe references recorded on a transaction are those assigned to the card at the time the transaction took place.\nIf the references are amended, they will only be applied to future transactions. \nExisting transaction are not affected.\n:::"
$ref: '#/components/schemas/CardReferences'
spending_limits:
description: 'All spending limits set for the card.
You can have at most 1 periodic (day/week/month/quarter/all-time) and 1 non-periodic (single transaction) limit at a time.
If you try to specify 2 periodic limits at a time, it will result in an error.'
type: object
$ref: '#/components/schemas/SpendingLimitsSchema'
spending_period:
description: 'The controls for the card''s spending period.
They let you set the dates when the card becomes available or unavailable for spending, and define what happens after the end date.
If specified, you must provide at least one of these:
- `start_date`
- `end_date` together with `end_date_action`
The dates provided must be in the future.'
type: object
allOf:
- $ref: '#/components/schemas/SpendingPeriodSchema'
categories:
type: array
description: 'The list of merchant categories to be available for card spending.
If not specified, all categories will be allowed.
:::note
The `categories` and `merchant_controls` parameters have the following restrictions:
- If you set `categories`, you **cannot** set `merchant_controls.control_type` to `allow`.
- You **can** set `merchant_controls.control_type` to `block`.
- You may also set **either** `categories` or `merchant_controls` independently, or **set neither**.
- Both parameters can be used together **only** if `merchant_controls.control_type` is `block`.
:::'
items:
$ref: '#/components/schemas/BusinessMerchantCategory'
merchant_controls:
description: "The merchant-level controls for card spending.\n\nThey let you block or allow the card to only transact with specific merchants: \n- `allow`: permits only the specified merchants (cannot be used if the `categories` parameter is set).\n- `block`: blocks the specified merchants (can be used with or without `categories`)."
type: object
$ref: '#/components/schemas/MerchantControlsSchema'
countries:
description: Restricts card use to specified countries, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) codes.
type: array
items:
type: string
pattern: ^[A-Z]{2}$
example: GB
accounts:
type: array
description: 'The list of accounts to link to the card.
If not specified, all accounts will be linked.
To retrieve account IDs, use the [`GET /accounts` operation](https://developer.revolut.com/docs/api/business#get-accounts).'
items:
type: string
format: uuid
required:
- request_id
- virtual
examples:
team_member_card:
$ref: '#/components/examples/cardIndividualCreate'
company_card:
$ref: '#/components/examples/cardCompanyCreate'
autogenerated_card:
$ref: '#/components/examples/cardAutogeneratedCreate'
card_with_spending_period_start_date:
$ref: '#/components/examples/cardWithSpendingPeriodStartDateCreate'
responses:
'200':
description: Information about the created card
content:
application/json:
schema:
$ref: '#/components/schemas/CardCreatedResponse'
examples:
team_member_card:
$ref: '#/components/examples/cardIndividualDetails'
company_card:
$ref: '#/components/examples/cardCompanyDetails'
autogenerated_card:
$ref: '#/components/examples/cardAutogeneratedDetails'
card_with_spending_period_start_date:
$ref: '#/components/examples/cardWithSpendingPeriodStartDateDetails'
'400':
description: "Bad Request\n\nReturned, for example, when your request is malformed, missing required fields, or when it contains fields that cannot co-exist or unsupported values.\n\nIf the invalid value is an array item, the error might indicate the array index of this faulty item, counting from `0`. \nFor example, if you provide the list of countries, such as `\"countries\": [\"GB\", \"USA\", ...]`, the first item (`GB`) has index `0`, the second item (`USA`) has index `1`, and so on.\nIn the example, `USA` is invalid, because it should be a 2-letter code.\nIn such a case, the error will indicate that `countries[1]` is invalid, thus pointing to the second item in the array, i.e. `USA`."
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_conditional_fields:
summary: Contact IDs or product are required when holder ID not provided
value:
code: 3000
message: Either contact_ids or product must be present when holder_id is empty
contact_ids_and_product_not_allowed_with_holder_id:
summary: Contact IDs and product are not allowed when holder ID present
value:
code: 3000
message: Both contact_ids and product must be empty when holder_id is present
references_not_allowed_with_holder_id:
summary: References are not allowed when holder ID present
value:
code: 3000
message: references must be empty when holder_id is present
missing_required_field:
summary: Merchant controls are missing merchant IDs
value:
code: 3000
message: merchant_ids is empty
invalid_json:
summary: Invalid request body
value:
code: 3000
message: 'Cannot parse request: invalid JSON'
product_not_found:
summary: Card product not found
value:
code: 2101
message: Product MJB not found
cannot_add_contact_ids:
summary: Contact ID(s) not found
value:
code: 2101
message: Unable to attach contactIds
wrong_spending_period_date:
summary: Wrong spending period date
value:
code: 2101
message: Spending period start_date must be in the future
invalid_account_id:
summary: Invalid account ID
value:
code: 2101
message: Invalid account ids provided=[0f187658-8c07-491f-9129-ae567b829137]
invalid_country_code:
$ref: '#/components/examples/cardErrorBadCountryCode'
'404':
description: 'Team member not found
Returned when the team member specified as cardholder in `holder_id` does not exist.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3042
message: Team member not found
'422':
description: 'Unprocessable entity
For example, the team member exceeds the limit for virtual cards per account, or an unexpected error occurred when the initial request with the same `request_id` was sent.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cards_limit_exceeded:
summary: Virtual cards limit per account exceeded
value:
code: 3087
message: Active virtual cards limit is exceeded for the employee
unexpected_error:
summary: Unexpected error on initial request
value:
code: 33009
message: 'Idempotent replay failed: first execution was not successful'
'429':
description: Concurrent requests with the same idempotency key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 3162
message: Parallel requests conflict. Please synchronize your requests. request_id=5baa6989-ae59-4668-bb09-042fca180518
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/cards/{card_id}:
get:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
summary: Retrieve card details
operationId: getCard
description: 'Get the details of a specific card, based on its ID.
:::note
- This feature is not available in Sandbox.
- To increase your account''s card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::
For more information, see the guides: [Manage cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards).'
security:
- AccessToken:
- READ
tags:
- Cards
parameters:
- name: card_id
in: path
required: true
description: The ID of the card.
schema:
type: string
format: uuid
responses:
'200':
description: Information about the card
content:
application/json:
schema:
$ref: '#/components/schemas/CardResponse'
examples:
virtual_card:
$ref: '#/components/examples/cardVirtualDetails'
physical_card:
$ref: '#/components/examples/cardPhysicalDetails'
card_with_spend_program:
$ref: '#/components/examples/cardWithSpendProgramDetails'
team_member_card:
$ref: '#/components/examples/cardIndividualDetails'
company_card:
$ref: '#/components/examples/cardCompanyDetails'
autogenerated_card:
$ref: '#/components/examples/cardAutogeneratedDetails'
card_with_spending_period_start_date:
$ref: '#/components/examples/cardWithSpendingPeriodStartDateDetails'
'400':
description: 'Bad request
Returned, for example, when you provide an invalid card ID in the path.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid_id:
$ref: '#/components/examples/cardErrorBadId'
'404':
description: Card doesn't exist
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: 1214
message: Card not found
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
servers:
- url: https://b2b.revolut.com/api/1.0
description: Production server (uses live data)
summary: Update card settings
operationId: updateCard
description: 'Update settings for a specific card, based on its ID.
:::note
- This feature is not available in Sandbox.
- To increase your account''s card limits, please contact [Revolut API Support](mailto:api-requests@revolut.com).
:::
:::warning
Some spend control parameters can affect one another.
When updating spend controls, review the resulting settings in the response to ensure they reflect the configuration you intended.
:::
For more information, see the guides: [Manage cards](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards).'
security:
- AccessToken:
- WRITE
tags:
- Cards
parameters:
- name: card_id
in: path
required: true
description: The ID of the card.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
properties:
label:
type: string
description: The label of the card.
maxLength: 30
spending_limits:
description: 'All spending limits set for the card.
You can have at most 1 periodic (day/week/month/quarter/all-time) and 1 non-periodic (single transaction) limit at a time.
If you try to specify 2 periodic limits at a time, it will result in an error.
Use `null` as the value for a specific limit to erase that limit.
Use `null` as the value for the `spending_limits` object to erase all limits.
:::note
Updating a spending limit does not reset the spending counter.
For more information, see the guides: [Manage cards - Update a card](https://developer.revolut.com/docs/guides/manage-accounts/cards/manage-cards#update-a-card).
:::'
type: object
$ref: '#/components/schemas/SpendingLimitsSchema'
spending_period:
description: 'The controls for the card''s spending period.
They let you set or modify the dates when the card becomes available or unavailable for spending, and define what happens after the end date.
If specified, you must provide at least one of these:
- `start_date`
- `end_date` together with `end_date_action`
The spending period dates must be in the future.
The dates are inclusive.
This means that:
- If you set the `start_date` to `2025-12-31`, the card will become active on that day.
- If you set the `end_date` to `2026-06-01`, the card will be active through that day, and will be locked/terminated starting on 2nd June 2026.
:::note []
If you wish to unlock a card with a spending period starting in the future and make it available for spending right away, you can do it in a few ways, depending on your use case:
- To remove the start date, but keep the end date settings, provide the current `spending_period` settings without the `start_date`.
- To remove the start date when no end date is set, provide the `spending_period.start_date` set to `null`.
- To remove **all** spending period settings, either provide `spending_period` set to `null`, or use the dedicated endpoint to [unlock](https://developer.revolut.com/docs/api/business#unlock-card) the card.
If you wish to erase a spending period end date, you can do this in a similar way, applying the steps to `spending_period.end_date` and `spending_period.end_date_action`.
:::'
type: object
allOf:
- $ref: '#/components/schemas/SpendingPeriodSchema'
categories:
type: array
description: 'The list of merchant categories that will be available for card spending.
Use `null` to erase the value and reset to empty (all categories will be allowed).
:::note
The `categories` and `merchant_controls` parameters have the following restrictions:
- If you set `categories`, you **cannot** set `merchant_controls.control_type` to `allow`.
- You **can** set `merchant_controls.control_type` to `block`.
- You may also set **either** `categories` or `merchant_controls` independently, or **set neither**.
- Both parameters can be used together **only** if `merchant_controls.control_type` is `block`.
:::'
items:
$ref: '#/components/schemas/BusinessMerchantCategory'
merchant_controls:
description: 'The merchant-level controls for card spending.
They let you block or allow the card to only transact with specific merchants:
- `allow`: permits only the specified merchants (cannot be used if the `categories` parameter is set).
- `block`: blocks the specified merchants (can be used with or without `categories`).'
type: object
$ref: '#/components/schemas/MerchantControlsSchema'
countries:
description: The list of countries where the card can be used, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) codes.
type: array
items:
type: string
pattern: ^[A-Z]{2}$
example: GB
accounts:
type: array
description: 'The list of accounts to link to the card.
If not specified, all accounts will be linked.
To retrieve account IDs, use the [`GET /accounts` operation](https://developer.revolut.com/docs/api/business#get-accounts).'
items:
type: string
format: uuid
examples:
update_all_properties:
summary: Update all properties
value:
label: New card label
spending_limits:
single:
amount: 100
currency: GBP
month:
amount: 300
currency: GBP
spending_period:
start_date: '2025-09-18'
end_date: '2026-12-20'
end_date_action: lock
categories:
- services
- shopping
- furniture
merchant_controls:
control_type: block
merchant_ids:
- 46df0a1b-3678-4ded-9cf5-9f4da1b5019d
- e8a8
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/revolut/refs/heads/main/openapi/revolut-cards-api-openapi.yml