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.

To receive updates:

1

Create an endpoint

Create an endpoint in your application to receive HTTP requests about your cards. See the events documentation.

2

Configure VGS Account Updater Notifications

Configure VGS Account Updater Notifications in your VGS Dashboard.

3

Enable Card Updates

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

Each notification includes a details block containing card_id.

5

Use the cardID to fetch the updated card data

Get Card - Get information on registered cards:

curl example

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

au_card.updated — Card Updated

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

au_card.expired — Card Expired

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

au_card.closed — Card Closed

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

au_card.contact_cardholder_advice — Card Contact Cardholder Advice

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

au_card.non_participating — Card Non-Participating

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

au_card.unknown — Card Unknown

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

au_card.enrolled — Card Enrolled

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

au_card.opt_out — Card Opt-Out

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.

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.

Reference

• Getting started with Account Updater

• VGS Account Updater API documentation