# Enroll Card - V1 Below is a diagram detailing how card data will flow to and from a customer's servers. ### Request Body Fields The table below contains more details on the request body fields, which are required and which are optional. | Field | Field Type | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | name | Required | Name of the user on the card | | number | Required | VGS alias representing the PAN | | exp\_month | Required | Expiration month on the card | | exp\_year | Required | Expiration year on the card | | billing\_address | Optional | Billing address registered on the card | | company | Optional | Company registered on the card | | address1 | Optional | Address1 of the user registered on the card | | address2 | Optional | Address2 of the user registered on the card | | city | Optional | City of the user registered on the card | | region | Optional | Region of the user registered on the card | | country | Optional | Country of the user registered on the card | | postal\_code | Optional | Postal Code of the user registered on the card | | phone | Optional | Phone Number of the user registered on the card | | merchant | Conditional Required (pass this value if you are submitting the card on behalf of a merchant or if you have multiple merchants registered for a single VGS vault) | "merchant" element in the request payload | | sub\_merchant\_name | Conditional Required (pass this value if you are submitting the card on behalf of a merchant) | Merchant Name registered on the card | | vgs\_merchant\_id | Conditional Required (required only if multiple merchants are registered per VGS vault for Account Updater) | VGS generated ID per merchant registered for VGS Vault. This ID is returned as a part of the merchant registration process for Account Updater | The following cURL command will enroll your card in VGS Account Updater. {% code title="Enroll Card (cURL)" %} ```bash curl https://calm..verygoodsecurity.app/cards \ -x https://@..verygoodproxy.com:8443 -k \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${VGS_ACCESS_TOKEN}" \ -d '{ "name": "John Doe", "number": "5573495XTjZP21V7312", "exp_month": 7, "exp_year": 24 }' ``` {% endcode %} After submitting the enrollment request, an immediate synchronous response is generated confirming the successful initiation of the enrollment process for updates with the payment service provider. This response provides details about the request's status, along with the associated event type received on the card. {% code title="Synchronous Response (example)" %} ```json { "data": { "id": "CRDuVQCsenqj6dbHFQq9gen2E", "name": "John Doe", "number": "5573495XTjZP21V7312", "exp_month": 7, "exp_year": 24, "capabilities": [ "ACCOUNT_UPDATER" ], "created_at": "2019-05-15T12:30:45Z", "updated_at": "2019-05-15T12:30:45Z", "state": "enrolled", "event": "au_card.updated" } } ``` {% endcode %} An asynchronous response is also sent via a webhook URL to you, if the enrollment does not complete immediately. The synchronous response will have the `state: ENROLLING` and not the final state of the request. {% hint style="info" %} No webhook event is sent if the enrollment returns `state: ENROLLED` in the response immediately. {% endhint %} ### Response Body Fields The table below provides detailed information about the fields in the synchronous response body for the Enroll Card request. | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | Serves as a unique identifier for the card within VGS Account Updater Service | | name | Name of the user on the card | | number | VGS alias representing the PAN | | exp\_month | Expiration month on the card | | exp\_year | Expiration year on the card | | billing\_address | Billing address registered on the card | | name | Name of the user on the card | | company | Company registered on the card | | address1 | Address1 of the user registered on the card | | address2 | Address2 of the user registered on the card | | city | City of the user registered on the card | | region | Region of the user registered on the card | | country | Country of the user registered on the card | | postal\_code | Postal Code of the user registered on the card | | phone | Phone Number of the user registered on the card | | capabilities | Indicates that the card is enrolled in the VGS Account Updater Service | | created\_at | Timestamp indicating when the card was enrolled with VGS Account Updater | | updated\_at | Timestamp indicating when an update was received for the card from the network | | state | Current state of the card in VGS | | event | Event or status update received from the network regarding the card. For more information on possible events, please refer to this [link](https://docs.verygoodsecurity.com/cmp/developer-resources/notifications) | #### VGS States and Network Events Reference For details about VGS states corresponding to various event types received on a card from the network, please refer to the documentation [here](https://docs.verygoodsecurity.com/cmp/developer-resources/notifications). {% hint style="info" %} Once a card update is received through the networks, the updated card information is generally considered usable. However, the timing and approach to updates can vary across issuers. Issuer Practices: * Some issuers send updates only after the cardholder activates the new physical card ("plastic"). * Others may allow the old and new card details to coexist temporarily, ensuring continuity in transactions during the transition. * No Uniform Pattern: There is no single standardized pattern across all issuers. Each issuer follows its internal policies regarding when updates are shared and how it handles card transitions. Merchants should consider these variations and ensure they accommodate both scenarios to minimize disruptions in recurring or tokenized transactions. {% endhint %} ### Mock Responses and Test Cards For test card numbers that you can use for testing in the Sandbox environment, see [Test Cards](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing).