Quickstart
You need to have VGS CLI version >=1.9.4 installed.
Get your cards enrolled with the VGS Account Updater to increase authorization acceptance of your payments. Follow those simple steps to get started.
Setup Outbound Route
To import the route configuration file on your VGS dashboard, follow these steps:
Using the Dashboard:
Navigate to the Addons section in your sandbox vault.
Select VGS CALM from the route template options.
Enable the switch for Account-Updater.
This will automatically add the route to your sandbox vault.
Using VGS CLI:
Alternatively, you can configure the route by importing the route configuration file (au_outbound.yaml) using the VGS CLI. Run the following command:
vgs apply routes --vault <YOUR-VAULT_ID> -f au_outbound.yamlExample of CLI command:
vgs apply routes --vault tntmhqqg8ew -f au_outbound.yamlObtain API Credentials
Integration with VGS Account Updater can start as soon as you create a service account with VGS CLI:
If Payment Orchestration credentials have already been provided by VGS Support, this section can be skipped. Use the Client ID and Secret provided by VGS Support to access the VGS Account Updater API
vgs generate service-account -t calm --var vault_id=YOUR-VAULT-ID > ./calm-credentials.yaml
vgs apply service-account -O YOUR-ORGANIZATION-ID -f ./calm_credentials.yaml
Now you can use your credentials to obtain access token
To obtain an access token with created credentials:
curl -X POST \\
-d "client_id=<CLIENT_ID>" \\
-d "client_secret=<CLIENT_SECRET>" \\
-d "grant_type=client_credentials" \\
"https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token"
Visit Authentication for more details and code snippets.
Enroll Card in VGS Account Updater
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.
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"
}
}
Response Body Fields
The table below provides detailed information about the fields in the synchronous response body for the Enroll Card request.
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
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.
Mock Responses and Test Cards
For test card numbers that you can use for testing in the Sandbox environment, see Test Cards.
Get Card
Get Card - Get information on registered cards
The following cURL command will get your card information from the VGS Account Updater.
curl --request GET https://calm.<ENVIRONMENT>.verygoodsecurity.app/cards/tok_svzgzzX8SDJMRjk93GVKG6b \
-x https://<CREDENTIALS>@<VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com:8443 -k \
-H "Content-type: application/json" \
-H "Authorization: Bearer \${VGS_ACCESS_TOKEN}"
VGS Account Updater returns a Card object in response to your API request.
{
"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.enrolled"
}
}
VGS States and Network Events
Outlined below are the VGS states corresponding to various event types received on a card from the network.
au_card.updated
enrolled
Account number change message This event is triggered when a cardholder opens a new account with a participating issuer or when a new card is issued. For e.g. this could be due to new account creation, lost or stolen card, or when a card holder gets upgraded to Platinum or downgraded, or, due to a portfolio change (one bank to other).
1. New VGS alias is returned in the “number” field in the response 2. New Expiration Month is returned in the “exp_month” field in the response 3. New Expiration Year is returned in the “exp_year” field in the response
au_card.expired
enrolled
Expiration date change This event denotes an expiration date change event. Whenever the card expires but has the same PAN, then, a new expiration date is issued. This event is an indication that the card expired (and so a new date is issued). Typically, cards have an expiration date of 2, 3 or x years (it used to be 5 but we rarely see them these days). Sometimes, an issuer can have an expiration for 1 year (for brand new card holders as they do not have enough credit).
1. New Expiration Month is returned in the “exp_month” field in the response 2. New Expiration Year is returned in the “exp_year” field in the response
au_card.closed
closed
Closed account advice This event is triggered when the issuer reports the closure of the cardholder's account i.e. cardholder's account associated with the particular card is no longer active/closed providing an important update for merchants to keep their records accurate and avoid attempting transactions with invalid or closed accounts.
Returned card data replicates the information provided in the request with the status as closed
au_card.non_participating
enrolled
Non-participating BIN This event represents a non-participating BIN event, indicating that cards linked to these BINs will not receive updates through the Account Updater service. i.e. BIN of a particular card is not participating in the Account Updater service and merchants subscribed to AU will not receive updates for cards associated with non-participating BINs.
Returned card data replicates the information provided in the request with the status as enrolled
au_card.contact_cardholder_advice
enrolled
Contact cardholder advice This event indicates the issuer is letting the merchant know that something has changed and the merchant should force the customer to key enter the credential and the update will not be shared via the account updater channel for the merchant. In short the merchant must contact the cardholder for more information or clarification.
Returned card data replicates the information provided in the request with the status as enrolled
au_card.unknown
enrolled
Account not found response from a participating BIN This event indicates that the card is eligible for automatic updates, but there are no match was found for this account.
Returned card data replicates the information provided in the request with the status as unknown
au_card.enrolled
enrolled
Match made, account number and expiration date unchanged This event implies that the card is already enrolled for Account Updater services, confirming the card's account number and expiration date haven't changed (matched) since the last card update.
Returned card data replicates the information provided in the request with the status as enrolled
au_card.opt_out
enrolled
Cardholder Opt-Out Note (Stop Advice) is placed on a card This event is triggered when the cardholder chooses to opt-out of the account updater service i.e. when the cardholder does not want their account information automatically updated through the AU service. Opting out is typically a deliberate choice made by the cardholder.
Returned card data replicates the information provided in the request with the status as enrolled
au_card.valid
enrolled/valid
Match made, account number and expiration date unchanged This event is triggered when the network confirms that the card status remains unchanged. Match made, account number and expiration date unchanged - This event implies that the card is already enrolled for Account Updater services, confirming the card's account number and expiration date haven't changed (matched) since the last card update.
au_card.valid event is exclusively available in the real-time card-check API response. In the context of the cards/ API, the corresponding event is represented as au_card.enrolled. Returned card data replicates the information provided in the request with the status as valid.
Receive Card Updates
Once a card is enrolled in VGS Account Updater, your server will receive updates on the registered card using VGS Account Updater Notifications.
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.
Sample Code
For a new vault, the procedure is the same except that aliases should be created beforehand. See our sample code, which shows how to redact a sample card data in your vault.
Reference
Last updated