# Virtual Cards
source: https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/vcn/index.md

The virtual card use cases illustrate the process of a partner creating, retrieving, updating, and deleting virtual cards.

To use the virtual card-related endpoints and manage virtual card details, you need to select the Card Management capability when setting up your project. Refer to Step 8 in the [Service Details](https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md#service-details) for more information.
Note: In the following diagrams, optional steps are denoted with dashed arrows instead of solid arrows.

## Create a virtual card {#create-a-virtual-card}

Partners use this endpoint to create a virtual card with authorization controls, card reconciliation data that is ready to be used for payments, and card user details. Card reconciliation data and card user details are not required to create the virtual card.

Optionally, you can add card reconciliation data and card user details after the initial creation of the virtual card.

Pre-requisite: [Register a real card](https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/rc/index.md#register-a-real-card).
Diagram vcncreate
API Reference: `POST /accounts/virtual-cards`


API Reference: `POST /accounts/virtual-cards/{account_id}/card-cdf-data`

## Manage a virtual card {#manage-a-virtual-card}

### Retrieve virtual card details {#retrieve-virtual-card-details}

Partners use this endpoint to retrieve virtual card details, authorization controls, card data, and card user details for an existing virtual card.
Diagram vcnretrievedet
API Reference: `GET /accounts/virtual-cards/{account_id}`

### Update virtual card details {#update-virtual-card-details}

Partners use this endpoint to update virtual card details for an existing virtual card.
Diagram vcnupdatedet
API Reference: `PUT /accounts/virtual-cards/{account_id}/card-details`

### Manage virtual card data {#manage-virtual-card-data}

Partners use these endpoints to update or delete card reconciliation data associated with a virtual card. Card reconciliation data are in Custom Data Fields (CDF) key value pairs.
Diagram vcncarddata
API Reference: `PUT /accounts/virtual-cards/{account_id}/card-cdf-data`


API Reference: `DELETE /accounts/virtual-cards/{account_id}/card-cdf-data`

## Search virtual card details {#search-virtual-card-details}

Partners use this endpoint to search for virtual card details with defined search parameters.
Parameter:

* Search by virtual `cardNumber`
* Search by `realCardID`

The search returns a list of virtual card numbers and the associated `accountid`.

The `accountid` can be used to retrieve additional virtual card details using the [Retrieve virtual card details](https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/vcn/index.md#manage-virtual-cards) endpoint.
Diagram vcnsearch
API Reference: `POST /accounts/virtual-cards/searches`

## Manage virtual card users {#manage-virtual-card-users}

### Add card user to an existing virtual card {#add-card-user-to-an-existing-virtual-card}

Partners use this endpoint to add a card user to an existing virtual card. To add a card user, you need:

1. Card Management capability and Mobile Virtual Card Management capability selected when setting up your project. Refer to Step 8 in the [Service Details](https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md#service-details) for more information.
2. Correct account ID for the specific virtual card.

Diagram vcn-add-carduser
API Reference: `POST /accounts/virtual-cards/{account_id}/card-user`

### Retrieve virtual card user details {#retrieve-virtual-card-user-details}

Partners use this endpoint to retrieve the user information associated with a specific virtual card account ID for the purposes of accessing and managing cardholder information. To get the card user details, you need:

1. Card Management capability and Mobile Virtual Card Management capability selected when setting up your project. Refer to Step 8 in the [Service Details](https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md#service-details) for more information.
2. Card user already associated with the specific virtual card.
3. Correct account ID for the specific virtual card.

Diagram vcn-get-carduser
API Reference: `GET /accounts/virtual-cards/{account_id}/card-user`

### Update card user details {#update-card-user-details}

Partners use this endpoint to update card user details for an existing virtual card to maintain accurate and up-to-date information. To update the card user details, you need:

1. Card Management capability and Mobile Virtual Card Management capability selected when setting up your project. Refer to Step 8 in the [Service Details](https://developer.mastercard.com/commercial-connect-api/documentation/quick-start-guide/index.md#service-details) for more information.
2. Card user already associated with the specific virtual card.
3. Correct account ID for the specific virtual card.

Diagram vcn-put-carduser
API Reference: `PUT /accounts/virtual-cards/{account_id}/card-user`

## Update a virtual card status {#update-a-virtual-card-status}

Partners use this endpoint to update the status of a virtual card.

The `ACTIVE` or `BLOCKED` statuses allows users to block or unblock a virtual card. This can be used to temporarily block all transactions on a virtual card.
Diagram vcnblock
API Reference: `PUT /accounts/virtual-cards/{account_id}/card-status`

## Delete virtual card {#delete-virtual-card}

Partners use this endpoint to delete a specific virtual card. Transactions cannot be completed on a virtual card after it has been deleted and the deletion cannot be reversed. For a temporary block on transactions for a virtual card, use [Update a virtual card status](https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/vcn/index.md#update-a-virtual-card-status).
Diagram vcndelete
API Reference: `DELETE /accounts/virtual-cards/{account_id}`