Network Token Events

After a Network Token has been enrolled, there are a few events which may occur to update the status of the Network Token. You may receive these status updates via our Webhook integration, or may notice them on the Usage Reports section of your organization's Dashboard.

Here is a brief explanation of what each status update means:

Status
Description

Updated

The network has updated the card metadata

Used

A network token was used in a transaction with an upstream PSP

Suspended

A network token has been suspended by the issuing card network (Mastercard, Visa, etc)

Activated

A network token has been activated following a suspension or updated

Deleted

A network token has been deleted via the API

Event Examples

Network Token Updated event - The network has updated the card metadata

{
  "description": "Network Token updated",
  "details": {
    "card_bin": "511410",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_last4": "2293",
    "created_at": "2024-12-12T09:59:44.667670",
    "exp_month": "10",
    "exp_year": "2027",
    "network_token": "",
    "network_token_id": "0e28d9f6-d8a3-43ca-9bd8-b99c477c2b4c",
    "network_token_last4": "5022",
    "pan_alias": "5114103XX3542293",
    "payment_account_reference": "",
    "state": "CARD_UPDATED",
    "tenant_id": "tntt0fzksdr",
    "updated_at": "2024-12-12T09:59:44.667670"
  },
  "event": "network_token.updated",
  "fingerprint": "2c365dba9f2bffbc16b2a487d6e95be8f693c3de5c049bbc3f87b4fdc2ab5f24",
  "grouping": "every_single",
  "id": "d82e56a0-3b6e-417a-a7cb-674f84d806e3",
  "integration_id": "INcBi2ziCXeweqC6VvDx6keX",
  "occurrence": 1,
  "org_id": "ACgzdqxQb4RyPyWsw97DVDDD",
  "producer": {
    "application_name": "calm-api",
    "application_protocol": "http"
  },
  "scope": "vault",
  "summary": "A Network Token for 5114103XX3542293 pan alias has been updated in vault tntt0fzksdr",
  "tenant": "tntt0fzksdr",
  "timestamp": "2024-12-16T18:30:25.383Z"
}

Network Token Suspended event - A network token has been suspended by the issuing card network (Mastercard, Visa, etc)

{
  "description": "Network Token updated",
  "details": {
    "card_bin": "511410",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_last4": "2293",
    "created_at": "2024-12-12T09:59:44.667670",
    "exp_month": "10",
    "exp_year": "2027",
    "network_token": "",
    "network_token_id": "0e28d9f6-d8a3-43ca-9bd8-b99c477c2b4c",
    "network_token_last4": "5022",
    "pan_alias": "5114103XX3542293",
    "payment_account_reference": "",
    "state": "SUSPENDED",
    "tenant_id": "tntt0fzksdr",
    "updated_at": "2024-12-12T09:59:44.667670"
  },
  "event": "network_token.updated",
  "fingerprint": "2c365dba9f2bffbc16b2a487d6e95be8f693c3de5c049bbc3f87b4fdc2ab5f24",
  "grouping": "every_single",
  "id": "d82e56a0-3b6e-417a-a7cb-674f84d806e3",
  "integration_id": "INcBi2ziCXeweqC6VvDx6keX",
  "occurrence": 1,
  "org_id": "ACgzdqxQb4RyPyWsw97DVDDD",
  "producer": {
    "application_name": "calm-api",
    "application_protocol": "http"
  },
  "scope": "vault",
  "summary": "A Network Token for 5114103XX3542293 pan alias has been updated in vault tntt0fzksdr",
  "tenant": "tntt0fzksdr",
  "timestamp": "2024-12-16T18:30:25.383Z"
}

Network Token Activated event - A network token has been activated following a suspension or update

{
  "description": "Network Token updated",
  "details": {
    "card_bin": "511410",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_last4": "2293",
    "created_at": "2024-12-12T09:59:44.667670",
    "exp_month": "10",
    "exp_year": "2027",
    "network_token": "",
    "network_token_id": "0e28d9f6-d8a3-43ca-9bd8-b99c477c2b4c",
    "network_token_last4": "5022",
    "pan_alias": "5114103XX3542293",
    "payment_account_reference": "",
    "state": "ACTIVATED",
    "tenant_id": "tntt0fzksdr",
    "updated_at": "2024-12-12T09:59:44.667670"
  },
  "event": "network_token.updated",
  "fingerprint": "691182df3e498546e801ecadd09cc5726d6f7f2b2571933f82d121a17903ba07",
  "grouping": "every_single",
  "id": "183123c6-917d-4fe9-bc1c-bbda0a2a0aa2",
  "integration_id": "INcBi2ziCXeweqC6VvDx6keX",
  "occurrence": 1,
  "org_id": "ACgzdqxQb4RyPyWsw97DVDDD",
  "producer": {
    "application_name": "calm-api",
    "application_protocol": "http"
  },
  "scope": "vault",
  "summary": "A Network Token for 5114103XX3542293 pan alias has been updated in vault tntt0fzksdr",
  "tenant": "tntt0fzksdr",
  "timestamp": "2024-12-12T10:02:51.293Z"
}

Network Token Deleted event - A network token has been deleted via the API

{
  "description": "Network Token updated",
  "details": {
    "card_bin": "511410",
    "card_exp_month": "12",
    "card_exp_year": "2025",
    "card_last4": "2293",
    "created_at": "2024-12-12T09:59:44.667670",
    "exp_month": "10",
    "exp_year": "2027",
    "network_token": "",
    "network_token_id": "0e28d9f6-d8a3-43ca-9bd8-b99c477c2b4c",
    "network_token_last4": "5022",
    "pan_alias": "5114103XX3542293",
    "payment_account_reference": "",
    "state": "DELETED",
    "tenant_id": "tntt0fzksdr",
    "updated_at": "2024-12-12T09:59:44.667670"
  },
  "event": "network_token.updated",
  "fingerprint": "2c365dba9f2bffbc16b2a487d6e95be8f693c3de5c049bbc3f87b4fdc2ab5f24",
  "grouping": "every_single",
  "id": "d82e56a0-3b6e-417a-a7cb-674f84d806e3",
  "integration_id": "INcBi2ziCXeweqC6VvDx6keX",
  "occurrence": 1,
  "org_id": "ACgzdqxQb4RyPyWsw97DVDDD",
  "producer": {
    "application_name": "calm-api",
    "application_protocol": "http"
  },
  "scope": "vault",
  "summary": "A Network Token for 5114103XX3542293 pan alias has been updated in vault tntt0fzksdr",
  "tenant": "tntt0fzksdr",
  "timestamp": "2024-12-16T18:30:25.383Z"
}

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.

Field
Data type
Occurrence
Min length
Max length
Description
Purpose/Usage

description

String

Optional

0

INF

Description of the event

Provides details about the nature of the event

details

-

Block containing card details.

Encapsulates relevant details of the card associated with the event

card_bin

String

Mandatory

0 (might be empty)

4

Recognize which bank or institution issued the original card

Bank Identification Number (BIN), which is the first six digits of a payment card number

card_exp_month

Number

Mandatory

4

4

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.

card_exp_year

Number

Mandatory

4

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

card_last4

Number

Mandatory

0 (might be empty)

4

The last four digits of the card number

Used for recurring payments and to determine what payment instrument was used for the transaction

created_at

DateTime

Mandatory

20

20

Date and Timestamp indicating NT creation

exp_month

Number

Mandatory

2

4

A two-digit value (from 01 to 12) indicates the month when the Network Token validity ends.

Network Token Expiration Month

exp_year

Number

Mandatory

4

4

A four-digit value indicating the year when the Network Token expires

Network Token Expiration Year

network_token

String

Mandatory

0 (might be empty)

32

Networks Generated representation of a payment card number used for processing Network Token transactions instead the actual card details for recurring payments

Used for recurring payments and to determine what payment instrument was used for the transaction

network_token_id

String - UUID

Mandatory

32

36

NT Identification on a network side

Leveraged in the reference for any additional details about the NT/Card directly with Networks, and for debugging with VGS along with trace_id, etc

network_token_last4

Number

Mandatory

4

4

Last four digits of the network token itself, not the original card number (PAN).

pan_alias

Number/String - Custom Identifier

Mandatory

Depends on the Alias format https://www.verygoodsecurity.com/docs/terminology/nomenclature#alias-formats

Depends on the Alias format https://www.verygoodsecurity.com/docs/terminology/nomenclature#alias-formats

A tokenized representation of sensitive data. Can be referenced at https://www.verygoodsecurity.com/docs/terminology/nomenclature#alias-formats

payment_account_reference

String

Mandatory

0 (might be empty)

29

Payment Account Reference (PAR) is a non-financial reference value assigned to each.

Used as a unique PAN to link a Payment Account represented by PAN and its affiliated Tokens. PAN refers to the card number of the cardholder's credit card, debit card, store credit. card, or gift card.

state

String

Mandatory

7

12

A status that is assigned to Network Token (NT) once it’s successfully provisioned. More at https://www.verygoodsecurity.com/docs/network-tokens/api/enroll-network-token#network-token-states

tenant_id

String - Custom identifier

Mandatory

10

10

Vault ID

Indicates the vault linked to this event, which can be found on your VGS Dashboard.

updated_at

String - Date-Time - ISO 8601

Mandatory

30

30

Date and Timestamp indicating Network Token last updated date on the VGS side

Network Token last updated date on VGS side

event

String

Mandatory

21

21

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

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

-

The 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

А day and timestamp of notification generation in VGS notification service.

Network Tokens Webhook

You can set up a webhook to receive Network Token updates by following the steps below:

  • Navigate to your Dashboard, and in the left-hand menu under Administration select Organization

  • On the Organization page, select the Notifications tab

  • Select Add a Notification, and enter the details for your Webhook as desired

  • After creation, search for network_token.updated in the events list

  • Configure the Vaults for which you want to subscribe to these notifications in the modal that appears

  • Press the Save button in the bottom right corner of the page

You should now start receiving updates for the Network Token Vaults for which you have subscribed.

What's next?

PreviousAPI ReferenceNextBulk Enrollment

Last updated