# Account Updater Notifications - V1 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](https://docs.verygoodsecurity.com/cmp/developer-resources/notifications). #### To receive updates: {% stepper %} {% step %} ### Create an endpoint Create an endpoint in your application to receive HTTP requests about your cards. See the [events](https://docs.verygoodsecurity.com/cmp/api-dev/account-updater-events) documentation. {% endstep %} {% step %} ### Configure VGS Account Updater Notifications [Configure VGS Account Updater Notifications](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/account-updater-webhooks) in your VGS Dashboard. {% endstep %} {% step %} ### Enable Card Updates Enable Card Updates to send card updates to your new endpoint. {% endstep %} {% endstepper %} ## 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: {% stepper %} {% step %} ### Enroll cards with the VGS Account Updater API {% endstep %} {% step %} ### Receive notifications for events like * Card updates * Expirations * Account closures * And others {% endstep %} {% step %} ### Signature Read more about [**webhook signature**](https://docs.verygoodsecurity.com/cmp/developer-resources/guides/testing/account-updater-webhooks) to configure authentication properly. {% endstep %} {% step %} ### Extract the cardID from each notification Each notification includes a details block containing card\_id. {% endstep %} {% step %} ### Use the cardID to fetch the updated card data Get Card - Get information on registered cards: {% code title="curl example" %} ```bash curl --request GET https://calm..verygoodsecurity.app/cards/CRDuVQCsenqj6dbHFQq9gen2E \ -x https://@..verygoodproxy.com:8443 -k \ -H "Content-type: application/json" \ -H "Authorization: Bearer ${VGS_ACCESS_TOKEN}" ``` {% endcode %} {% endstep %} {% endstepper %} 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm/account-updater-v1/api-reference-v1/enroll-card-v1). ```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 } } ``` ### au\_card.updated — Card Updated Once your card account number or expiration date has been changed. au\_card.updated Response ```json { "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" } ``` ### au\_card.expired — Card Expired Once your card has expired. au\_card.expired Response ```json { "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" } ``` ### au\_card.closed — Card Closed Once your card account is closed. au\_card.closed Response ```json { "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" } ``` ### au\_card.contact\_cardholder\_advice — Card Contact Cardholder Advice au\_card.contact\_cardholder\_advice Response ```json { "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" } ``` ### au\_card.non\_participating — Card Non-Participating au\_card.non\_participating Response ```json { "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" } ``` ### au\_card.unknown — Card Unknown au\_card.unknown Response ```json { "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" } ``` ### au\_card.enrolled — Card Enrolled au\_card.enrolled Response ```json { "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" } ``` ### au\_card.opt\_out — Card Opt-Out au\_card.opt\_out Response ```json { "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. | Fields | Data type | Occurrence | Min length | Max length | Description | Purpose/Usage | | --------------------- | ------------------------------------------------------- | ---------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | description | String | Optional | 31 | 31 | 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/account-updater). ## Reference * [Getting started with Account Updater](https://docs.verygoodsecurity.com/cmp/products-and-services/account-updater#product-overview) * [VGS Account Updater API documentation](https://docs.verygoodsecurity.com/cmp/api-dev/account-updater)