Notifications
Stay informed about your VGS Account Updater-enrolled cards! Enable Push Updates to automatically receive account information without manual checks. Learn more about notifications in the Notification Center.
To receive updates:
Create an endpoint in your application to receive HTTP requests about your cards. See the events documentation.
Configure VGS Account Updater Notifications in your VGS Dashboard.
Enable Card Updates to send card updates to your new endpoint.
Configure VGS Account Updater Notifications
To set up the webhook endpoints, go to the Organization Settings > Notifications tab on your dashboard, click Add Notifications on the right and add your webhook where you will receive notifications.
After notifications are setup, you can configure cards events to send updates to your application endpoint. See the Add Card Events section below for more details on setting up these events.
Add Card Events
To get card lifecycle notifications you need to add them to your webhook configuration.
After you added the event, please select a vault within which you want to receive it.
Events
When you enroll cards using the VGS Account Updater API, you'll receive convenient notifications for lifecycle events. Each notification includes the card ID, allowing you to quickly fetch the latest card data using a simple GET request. Here's how it works:
1. Enroll cards with the VGS Account Updater API
2. Receive notifications for events like
Card updates
Expirations
Account closures
And others
3. Signature - Read more about webhook signature to configure authentication properly
4. Extract the cardID from each notification
5. Use the cardID to make a GET request to retrieve the updated card data
Get Card - Get information on registered cards
curl --request GET https://calm.<ENVIRONMENT>.verygoodsecurity.app/cards/CRDuVQCsenqj6dbHFQq9gen2E \
-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 immediately in response to your API request, providing a synchronous response. For details on request and response fields, please refer to Enroll 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
}
}
Card Updated event - once your card account number or expiration date has been changed.
au_card.updated Response
{
"description": "Card updated",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"new_account_number": "************5698",
"new_expiration_date": "0227",
"occurred_at": "2024-01-17T00:00Z",
"old_account_number": "************7343",
"old_expiration_date": "0424"
},
"event": "au_card.updated",
"fingerprint": "0734f9289326955d9b323c26b281fd8112f78ef56acd09a3dc2b8c7a9a13c948",
"grouping": "every_single",
"id": "bba88542-cfb1-42f8-8f63-aba60d62917c",
"integration_id": "IN6VgSvLVRV2j2iuxugi4mh7",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has been updated within vault tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-18T23:49:31.809Z"
}
Card Expired event - once your card has expired.
au_card.expired Response
{
"description": "Card expired",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"new_account_number": "************7343",
"new_expiration_date": "0427",
"occurred_at": "2024-01-17T00:00Z",
"old_account_number": "************7343",
"old_expiration_date": "0224"
},
"event": "au_card.expired",
"fingerprint": "a9f7f574f9df11acee08aecb9292b6aee2607ca6923893214450e2ddaf3e9fb2",
"grouping": "every_single",
"id": "72a57889-48e2-41a2-bad1-777dba7455b5",
"integration_id": "IN6VgSvLVRV2j2iuxugi4mh7",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has been expired within vault tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-19T00:04:39.891Z"
}
Card Closed event - once your card account is closed.
au_card.closed Response
{
"description": "Card closed",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z",
"old_account_number": "************7343",
"old_expiration_date": "0424"
},
"event": "au_card.closed",
"fingerprint": "a786596550eb3a2ef0e33ae58c2b74253e9e7ce6661326bb00c643add7032ccd",
"grouping": "every_single",
"id": "6c8c259c-1e42-48a9-864c-80c61c6c2fba",
"integration_id": "IN6VgSvLVRV2j2iuxugi4mh7",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has been closed within vault tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-19T00:07:27.836Z"
}
Card Contact Cardholder Advice event
au_card.contact_cardholder_advice Response
{
"description": "Card Contact Cardholder Advice",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z",
"old_account_number": "************7343",
"old_expiration_date": "0424"
},
"event": "au_card.contact_cardholder_advice",
"fingerprint": "c3168b4820cfb68f7e5fb8e3744bfa8efb340021660ec0180471177f8db0ec1d",
"grouping": "every_single",
"id": "64cb7832-56e6-46c5-b3fe-611cfbd3d954",
"integration_id": "INwhuRND8kbbUL6Yv9QudB9w",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has opted out and the merchant needs to contact cardholder for tenant tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-24T17:51:37.473Z"
}
Card Non-Participating event
au_card.non_participating Response
{
"description": "Card Non-Participating",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z"
},
"event": "au_card.non_participating",
"fingerprint": "c16a070bc351c29bd0a74c504dc1c727a8ea641478000b5251bcedf931e4c0ee",
"grouping": "every_single",
"id": "bae8eb84-2197-4d78-9742-d9fc14992d12",
"integration_id": "INwhuRND8kbbUL6Yv9QudB9w",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" is not participating for tenant tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-24T18:03:57.032Z"
}
Card Unknown event
au_card.unknown Response
{
"description": "Card Valid",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z"
},
"event": "au_card.unknown",
"fingerprint": "369a1a951d2131450953b68c678bff7f052c519ac85946859275efb392fb2cce",
"grouping": "every_single",
"id": "41e13908-b5d1-4d71-96d7-13186e7f7e64",
"integration_id": "INs4MeN1xjpQniQtZBR7VSg5",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" is valid for tenant tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-24T19:46:50.349Z"
}
Card Enrolled event
au_card.enrolled Response
{
"description": "Card Enrolled",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z"
},
"event": "au_card.enrolled",
"fingerprint": "46c9722d2f3ff2e130acf530ae43d8e277cb3586e5ced98ebccbf032d21c0741",
"grouping": "every_single",
"id": "cc42d364-e38f-4631-8363-a8782f7e463b",
"integration_id": "INs4MeN1xjpQniQtZBR7VSg5",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" enrolled for tenant tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-24T19:45:06.768Z"
}
Card Opt-Out event
au_card.opt_out Response
{
"description": "Card Opt Out",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"occurred_at": "2024-01-17T00:00Z"
},
"event": "au_card.opt_out",
"fingerprint": "4f7451324fcb50779abd62fb2eda31f604b8b99d334f5c0de43e7f28571d1089",
"grouping": "every_single",
"id": "765719b8-8c9d-4456-89b7-9a98a51edca2",
"integration_id": "INmPVDZzkSos7CnsjCBQCRgf",
"occurrence": 1,
"org_id": "AC21kskfJCLyrkVjmAT6gU9X",
"producer": {
"application_name": "calm-api",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has opted out for tenant tntvlyn1nof",
"tenant": "tntvlyn1nof",
"timestamp": "2024-01-25T16:01:38.719Z"
}
Notification Response Body Fields
The table below provides detailed information about the fields in the asynchronous notification response body for updates received on a card.
description
String
Optional
0
INF
Description of the event
Provides details about the nature of the event
details
JSON String
Optional
0
INF
Block containing card details. Includes: card_id and occurred_at
Encapsulates relevant details of the card associated with the event
card_id
String - Custom identifier
Mandatory
25
25
System-generated ID for the card in VGS
Serves as a unique identifier for the card within VGS Account Updater Service
occurred_at
String - Date-Time - ISO 8601
Optional
24
26
Timestamp of when the event was generated or occurred.
Records the exact timestamp when the event was generated or occurred
new_account_number
Number - Masked
Mandatory
16
16
Masked new account number on the card
Indicates an account update on the card, allowing the use of the last 4 digits of the new number
new_expiration_date
Number
Mandatory
4
4
New expiration date of the card
Indicates an updated expiration date for the card, making the new date readily available
old_account_number
Number - Masked
Mandatory
16
16
Masked old account number of the card
Records the exact timestamp when the event was generated or occurred
old_expiration_date
Number
Mandatory
4
4
Old expiration date of the card
Reflects the previous expiration date before the update, indicating a change in the expiration date
event
String
Mandatory
14
33
Event or status update received from the network regarding the card
Reflects the actual state or event of the card as received from the network. For more information on possible events, please refer to this link
exp_month
Number
Mandatory
1
2
A two-digit value (from 01 to 12) indicating the month when the card's validity ends.
Verifies the token's validity or match it with the expiration details on file during payment transactions.
exp_year
Number
Mandatory
2
4
A four-digit value indicating the year when the card expires
Determines whether the tokenized card is still valid, ensuring that the payment process proceeds smoothly
created_at
DateTime
Mandatory
20
20
Timestamp indicating when a specific account update (like a card update) was created or processed
Tracks the moment when the card record was created in VGS Vault
event
String
Mandatory
14
33
Event or status update received from the network regarding the card
Reflects the actual state or event of the card as received from the network. For more information on possible events, please refer to this link
fingerprint
String - Custom identifier - Hexadecimal representation
Mandatory
64
64
Hexadecimal SHA-256 hash of event+details+tenant
Enables grouping and throttling of similar messages based on the fingerprint, set by the producer as exp_repeat instead of individual occurrences
grouping
String
Mandatory
9
12
Method for grouping similar events by fingerprint
Allows throttling of requests based on the same fingerprint, grouping as exp_repeat, every_single, or high_rate
id
String - UUID
Mandatory
36
36
Unique ID for the request
Serves as a unique identifier for the request
integration_id
String - Custom identifier - Base62-encoded
Mandatory
24
24
Unique integration ID for this webhook
Identifies the webhook integration associated with this notification
occurrence
int
Mandatory
1
1
Grouping-related field; set to 1 if no grouping is applied
Represents the occurrence count if events are grouped; defaults to 1 if no grouping
org_id
String - Custom identifier
Mandatory
24
24
Organization ID
Indicates the organization ID linked to this event, which can be found on your VGS Dashboard.
producer
-
Originator of the event
Identifies the source system or entity generating the event
application_name
String
Optional
0
INF
Name of the producer application
Provides the name of the application responsible for generating this event
application_protocol
String - Protocol Identifier
Optional
4
5
Protocol used by the producer application
Specifies the protocol used by the application for this event
scope
String - Scope Identifier
Mandatory
5
5
Scope of the event notification
Used internally to populate additional fields based on the event scope
summary
String
Optional
0
INF
Summary of the notification
Offers a concise overview of the notification
tenant
String - Custom identifier
Mandatory
11
11
Vault ID
Indicates the vault linked to this event, which can be found on your VGS Dashboard.
timestamp
String - Date-Time - ISO 8601
Mandatory
24
26
Date and time when a specific update to a cardholder’s card information was updated by Networks
Track the exact day and time when a card's details were updated, such as a new expiration date or card number.
Testing
When testing using the VGS Account Updater sandbox, push notifications will be sent out immediately after enrolling a card. The exact notification type that gets sent out is determined based on the last digit in the card number. The map of which digits line up to which notification types is documented in the VGS Account Updater API Reference
Reference
Last updated