# 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. However, you need to apply at least one limit control to the newly created 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). Note: To email virtual cards, you can use the initiate payment endpoint. The supported use cases for payment initiation endpoint are dependent on the user's capability selection. For Card Management-only users, email is the only supported payment channel, allowing the ability to use an existing InControl virtual card or create a new virtual card at the time of request. For more information, see [Initiate payment](https://developer.mastercard.com/commercial-connect-api/documentation/use-cases/payments/index.md#initiate-payment). 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 `account_id`. The `account_id` 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. If both the issuer and the company have opted in for this feature, at this point in your request payload, you will need to provide a delivery method: * App delivery method enables integrators to deliver the virtual card to the user's account on the Mastercard InControl Pay App. * Web Push Provisioning (WPP) delivery method enables integrators to deliver virtual cards to card users through a Mastercard-hosted Add-to-Wallet website, with optional security checks (accessKey/accessCode) with a One-Time Authentication code (OTA) sent to the user's phone number. From there, the user can directly add the card to their mobile wallet, such as Apple wallet or Google Pay wallet. * Email supports the legacy workflow but is not recommended for use If you set WPP as your delivery method, you have the option to provide `wppDetails` in your request payload. If you choose to provide `wppDetails`, the card user will receive a prompt to enter the `accessCode` and get verified. After successful verification, the user will receive an OTP (one-time access passcode) sent to the associated phone number. The user must enter the code to get access to the virtual card. If you do not provide `wppDetails` in your request payload, the card user will receive a prompt to enter their phone number. If the phone number passes verification, the user will receive an OTP to the phone. The user must enter the code to get access to the virtual card. The choice of delivery method depends on your use case. If app adoption is low or impractical and based on one-time usage, consider using WPP as your delivery method. For example, if an airline issues a meal voucher as a virtual card, you can use WPP as an easy-to-use, convenient delivery method. If the end user prefers to manage the virtual card through an app experience, consider using the Mastercard InControl Pay App as the delivery method. 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. Note: When a virtual card status is `BLOCKED`, you cannot update either `cardDetails` (expiration) or `cardControls`. Any authorizations (charges) on virtual cards will be declined. 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}`