# Manage cards for your business

:::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).
:::

The Business API lets you issue and manage cards for your business.

- **Create or delete**: [Create](#create-a-virtual-card) a new virtual card, or [terminate](#terminate-a-card) a card when you want to cancel your card permanently.
- **Update**: [Update card settings](#update-card-settings), such as the card's label, linked accounts, or spending controls, [update contacts](#update-card-contacts) or [update references](#update-card-references) for a specific card.
- **Get details**: [Retrieve the list of cards](#retrieve-a-list-of-cards) issued for your team, [retrieve a specific card](#retrieve-a-specific-card) by its ID, or [retrieve sensitive details](#retrieve-sensitive-card-details) for a specific card.
- **Block or unblock**: [Freeze](#freeze-a-card) a card to make it temporarily unavailable for spending or [lock](#lock-a-card) a card as admin; to revert, [unfreeze](#unfreeze-a-card) or [unlock](#unlock-a-card) it to re-enable spending for the card.

:::tip
- To request a physical card, use the [Revolut Business app](https://business.revolut.com/login).
- To issue cards to team members pending onboarding completion, use the [Card invitations API](/docs/guides/manage-accounts/cards/manage-card-invitations) instead.
:::

## Different types of cards

You can create the following types of business virtual cards:

- **Team member cards:** Cards issued in the individual's name, where the individual [team member](/docs/guides/manage-accounts/teams/manage-team-members#about-team-members) is the cardholder.
  To create this card, specify team member in [`holder_id`](/docs/api/business#create-card#request).
- **Company cards:** Cards issued in the [business](/docs/guides/manage-accounts/get-started/sign-up-for-revolut-business-account)'s name, where the business is the cardholder, and up to 5 team members are added as card contacts.
  Card contacts can access card details and make payments on behalf of the business.
  As these cards aren't issued to a single team member, `holder_id` is not present.
  Instead, they have `contact_ids`, which lists the IDs of 1–5 team members added as contacts for the card.
  Unlike cardholders for team member cards, card contacts can be reassigned throughout the lifetime of the card.
  However, there must always be at least 1 card contact assigned at any given time.
- **Auto-issued cards**: Available only to [travel intermediaries](https://www.revolut.com/business/business-resources-travel/) at this time, these cards are issued in the business's name and intended for server-to-server transactions.
  As such, they do not require card contacts to be assigned and may pass through frictionless 3DS verification.
  To create an auto-issued card, leave `holder_id` and `contact_ids` empty.

  :::note
  To use auto-issued cards, please contact [Revolut API Support](mailto:api-requests@revolut.com).
  :::

## Create a virtual card

To create a new card, you must provide the following information:

::::details [Required details]

- **Request ID**: The ID of the request, provided by you to help you identify the creation request in your system.

  :::warning
  To ensure that a card creation is not processed multiple times if there are network or system errors, the same `request_id` should be used for requests related to the same card. For more details, see the [Idempotency](#idempotency) section.
  :::

- **Virtual**: Confirms that the card that you're creating will be virtual. Set it to `true`.

::::

Optionally, you can also specify additional details, such as a distinct label, linked accounts, and spending limits and categories.

::::details [Optional details]

- **Holder ID**: Specify the ID of the team member to assign as the holder of the card.
  Provide for [team member cards](#different-types-of-cards).
  For virtual cards (`virtual=true`), this field is optional.
  If not provided, the type of the issued card depends on the presence of contact IDs:

  - If contact IDs are provided, the card will be a company card.
  - If contact IDs are not specified, the card will be an auto-issued card.

- **Contact IDs**: Specify IDs of 1-5 team members to assign to the card as contacts. Provide for [company cards](#different-types-of-cards).

- **Label**: Give the card a label that will be displayed in the UI and in transaction reporting, to help with recognition and reconciliation.

- **References**: Provide references for the card for easier transaction tracking.
  You can assign up to 5 name-value pairs, where the names must be unique.
  They can be amended up to 10 times.

  :::note
  References are supported **only** for [auto-issued](#different-types-of-cards) or [company cards](#different-types-of-cards).
  They're not allowed for [team member cards](#different-types-of-cards).
  :::

- **Spending limits**: Set one of the periodic (day/week/month/quarter/year/all time) limits and/or a non-periodic (single) spending limit.

- **Spending period**: Set dates after which the card becomes available or unavailable for spending and define what happens when the end date is reached.

- **Categories**: Limit the merchant categories available for spending. By default, all are available. For the full list of categories, see the [API reference](/docs/api/business#create-card) → `categories`.

  :::note
  If you restrict merchant categories, you cannot use merchant controls to **allow** specific merchants.
  However, you can still use merchant controls with categories to **block** specific merchants.

  If you set only categories or only merchant controls, each works independently.
  :::

- **Merchant controls**: Block or allow the card to only transact with specific merchants.

  :::note
  If you restrict merchant categories, you cannot use merchant controls to **allow** specific merchants.
  However, you can still use merchant controls with categories to **block** specific merchants.

  If you set only categories or only merchant controls, each works independently.
  :::

  For more details, see the [API reference](/docs/api/business#create-card).

- **Countries**: Restrict card use to specified countries, provided as 2-letter [ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) codes.

- **Accounts**: Limit which accounts the card should be linked to, by providing their IDs. By default, all are linked.

::::

Travel intermediaries using our [travel solution](https://www.revolut.com/business/business-resources-travel/) also have access to a dedicated field.

::::details [Additional details for travel intermediaries]

- **Product**: Specify the card product offered by the card provider, i.e. the program under which this card should be issued.

  :::note
  - This field is supported **only** for [auto-issued cards](#different-types-of-cards) (required) or [company cards](#different-types-of-cards) (optional).
  It's not allowed for [team member cards](#different-types-of-cards).
  - To use this field, please contact [API Support team](mailto:api-support@revolut.com).
  :::

::::

For sample requests and responses:

[See the API reference: Create a card](/docs/api/business#create-card)

### Idempotency

To ensure that a card creation is not processed multiple times if there are network or system errors, we deduplicate requests made with the same request ID within a 24-hour interval (counting from the first request).
This is why you should use the same request ID for requests related to the same card.

This also means that if the first request fails, this state is saved and returned in response to all the subsequent requests with the same request ID within the 24-hour deduplication period.
An exception is when the initial request fails for an unexpected reason.
In such a case, you still get an error saying that the first execution was not successful, but you don't get the exact error message and code that might have been returned for that first execution, you only see that the idempotent replay failed.

While there is no specific requirement regarding the format of the request ID that you should use, we recommend using v4 UUIDs.

## Update a card

Depending on what you need to update, you have a few endpoints at your disposal. You can:

- [Update card settings](#update-card-settings), such as the label, accounts, or spending controls
- [Update card contacts](#update-card-contacts)
- [Update card references](#update-card-references)

### Update card settings

For each active card issued for your business, you can update its label displayed in the app, the merchant categories and countries available for spending, the spending limits, merchant-level controls and spending period, and the accounts the card is linked to.
You can update a single parameter or multiple parameters at once.

Note that you cannot restrict categories and allow specific merchants at the same time. For more information, see: [Create a virtual card](#create-a-virtual-card) → **Optional details**.

To reset the categories to default or erase a spending limit, provide `null` as the value for the respective parameter.

:::warning
- If the card has a [spend program](https://help.revolut.com/business/help/making-paymentsbusiness/spend-controls/setting-card-presets-for-my-team-members/) assigned, modifying the card's spend controls via the API will unlink this spend program from this card, and the new custom settings will apply.

- Updating a spending limit does not reset the spending counter.
  For example, if you create a card with a weekly spending limit of £50 on Monday, spend £25 with that card on Tuesday, and update the weekly spending limit to £30 on Wednesday, you'll only have £5 left to spend that week.
:::

A sample request looks like this:

```shell
curl -X PATCH https://b2b.revolut.com/api/1.0/cards/{card_id} \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '{
  "label": "New label",
  "categories": [
    "services",
    "shopping",
    "furniture"
  ],
  "spending_limits": {
    "single": null
  }
}'
```

For more details and example requests and responses:

[See the API reference: Update card settings](/docs/api/business#update-card)

### Update card contacts

Card contacts are team members assigned to [company cards](#different-types-of-cards).
They can access card details and make payments on behalf of the business.
Unlike cardholders for [team member cards](#different-types-of-cards), card contacts can be reassigned, and there can be more than 1 card contact (up to 5 at a time).

You can only update contacts for a card that already has some contacts assigned, and you cannot remove contacts from a card completely – a company card must always have at least 1 card contact assigned at any given time.

:::warning
This operation **overrides** the existing contacts. This means that it removes the current list completely, and replaces it with the new one provided in this request.

If you want to add new contacts for the card instead of replacing the existing ones, make sure that you [fetch](/docs/api/business#update-card-contacts) the existing contacts first, and include them in your request.
:::

```shell
curl -X PUT https://b2b.revolut.com/api/1.0/cards/{card_id}/contacts \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '[
  "3ea984a5-d599-4c97-b2b3-c6c12bb9b5e9",
  "02b969cb-b984-4a70-873d-f93220805e5e",
  "36d9604d-4821-45fc-bf1a-a2881f6336c0"
]'
```

For more details and example requests and responses:

[See the API reference: Update card contacts](/docs/api/business#update-card-contacts)

### Update card references

Card references are additional information that can be added to [company](#different-types-of-cards) or [auto-issued cards](#different-types-of-cards) to facilitate tracking transactions made with those card.

They take the form of key-value pairs, where each key (`name`) and value (`value`) can have up to 30 characters.
You can add up to 5 such pairs to a card.
References can be amended up to 10 times.

To remove existing references, simply provide an empty list.

:::warning
This operation **overrides** the existing references. This means that it removes the current list completely, and replaces it with the new one provided in this request.

If you want to add new references for the card instead of replacing the existing ones, make sure that you [fetch](/docs/api/business#update-card-references) the existing references first, and include them in your request.
:::

```shell
curl -X PUT https://b2b.revolut.com/api/1.0/cards/{card_id}/references \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '[
  {
    "name": "Budget",
    "value": "Engagement"
  },
  {
    "name": "Department",
    "value": "Business"
  }
]'
```

For more details and example requests and responses:

[See the API reference: Update card references](/docs/api/business#update-card-references)

## Retrieve cards

The Business API lets you retrieve the cards issued for your business.

When you retrieve the cards, for each card, you get its [details](#create-a-virtual-card), such as the card ID, the last 4 digits of its PAN, expiry date, current state, its type, and more.

You can:

- [Retrieve all the cards](#retrieve-a-list-of-cards) in your account
- [Retrieve a specific card](#retrieve-a-specific-card)

### Retrieve a list of cards

You can list all the cards [issued](#create-a-virtual-card) for your business.
You can also [filter](#filtering-and-pagination) the cards by their creation date.

The results are [paginated](#filtering-and-pagination) and sorted by the `created_at` date in reverse chronological order.

For more details and example requests and responses:

[See the API reference: Retrieve a list of cards](/docs/api/business#get-cards)

#### Filtering and pagination

When retrieving cards, you can also include the optional query parameters to:

- Modify the maximum number of cards returned per page (by default, it's `100`)
- Retrieve only the cards which were created before a date/date-time that you specify

For example, these parameters limit the number of cards to three and retrieve only the cards created before 13th June 2023:

```
/cards?limit=3&created_before=2023-06-13
```

To get to the next page, make a new request and use the `created_at` date of the last returned card as `created_before`.

### Retrieve a specific card

You can also retrieve a single specific card by its ID to look up its [details](#create-a-virtual-card).

:::note
To retrieve sensitive card details, you must use a different, [dedicated endpoint](#retrieve-sensitive-card-details).
:::

For more details and example requests and responses:

[See the API reference: Retrieve card details](/docs/api/business#get-card)

## Retrieve sensitive card details

To retrieve sensitive details of a card, such as its PAN (Primary Account Number), CVV (Card Verification Value) and expiry date, use this dedicated endpoint.

:::note
This endpoint requires the `READ_SENSITIVE_CARD_DATA` token [scope](/docs/guides/manage-accounts/get-started/make-your-first-api-request#3-get-an-access-token).
:::

In your request, provide the ID of the card for which you want to retrieve the sensitive details.

For more details and example requests and responses:

[See the API reference: Retrieve sensitive card details](/docs/api/business#get-sensitive-card-details)

## Freeze or unfreeze cards

You can [freeze](#freeze-a-card) an active card to make it temporarily unavailable for spending, or you can [unfreeze](#unfreeze-a-card) a frozen card to re-enable spending for that card.

:::note
To freeze or unfreeze cards via API, the access token used for the request must have the `WRITE` [scope](/docs/guides/manage-accounts/get-started/make-your-first-api-request#3-get-an-access-token).
:::

:::tip
- As a cardholder/card contact or admin, you can also freeze or unfreeze a card in the Revolut Business app.

- If you want to cancel your card permanently instead, you can [terminate](#terminate-a-card) it.
:::

### Freeze a card

To freeze a card, provide its ID in the request to the `freeze` endpoint.
On success, the card's state changes to `frozen` and no content is returned in the response.

For more details and example requests and responses:

[See the API reference: Freeze a card](/docs/api/business#freeze-card)

### Unfreeze a card

To unfreeze a card, provide its ID in the request to the `unfreeze` endpoint.
On success, the card's state changes to `active` and no content is returned in the response.

For more details and example requests and responses:

[See the API reference: Unfreeze a card](/docs/api/business#unfreeze-card)

## Lock or unlock cards

You can [apply an admin lock](#lock-a-card) to a card to make it temporarily unavailable for spending, or you can [unlock an admin-locked card](#unlock-a-card) to re-enable spending for that card.

:::note
To lock or unlock cards via API, the access token used for the request must have the `WRITE` [scope](/docs/guides/manage-accounts/get-started/make-your-first-api-request#3-get-an-access-token).
:::

:::tip
As an admin, you can also lock or unlock a card in the Revolut Business app.

Note that only members with the **Manage Cards** permission can lock or unlock cards in-app.
If the team member does not have this permission, they won't be able to lock or unlock the card.
:::

### Lock a card

To apply an admin lock to a card, provide the card's ID in the request to the `lock` endpoint.
On success, the card's state changes to `locked` and no content is returned in the response.

For more details and example requests and responses:

[See the API reference: Lock a card](/docs/api/business#lock-card)

### Unlock a card

To unlock an admin-locked card, provide its ID in the request to the `unlock` endpoint.
On success, the card's state changes to `active` and no content is returned in the response.

For more details and example requests and responses:

[See the API reference: Unlock a card](/docs/api/business#unlock-card)

## Terminate a card

When you want to cancel your card permanently, you can terminate it.
Once the card is terminated, it will no longer be returned by the API or appear in your cards.

:::warning
Card termination cannot be undone, so exercise caution and make sure that you understand the implications before you proceed.
:::

To terminate a card, provide its ID.

On success, the card is removed from your cards and no content is returned.

For more details and example requests and responses:

[See the API reference: Terminate a card](/docs/api/business#delete-card)