Enroll Card

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.

curl https://calm.<ENVIRONMENT>.verygoodsecurity.app/cards \
-x https://<CREDENTIALS>@<VAULT_ID>.<ENVIRONMENT>.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
    }'

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.

{
  "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"
  }
}

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.

Note: No webhook event is sent if the enrollment returns state: ENROLLED in the response immediately.

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

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.

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

Mock Responses and Test Cards

For test card numbers that you can use for testing in the Sandbox environment, see Test Cards.