Vault Documentation

Network Token Events

Network token events

After a Network Token has been enrolled, there are a few key events that may occur. These fall into two broad categories:

  • Lifecycle Events: These represent billable actions that typically result in a change to the card metadata or indicate successful provisioning.
  • Status Updates: These reflect changes to the token's status (e.g., suspended or deleted) and are not billable. You may receive these events via our Webhook integration or view them in the Usage Reports section of your organization's Dashboard. Below is an explanation of each:
Network Token Status VGS Network Token State VGS Reason Code Description Classification Type
Updated CARD_UPDATED cmp_card_updated The network has updated the card metadata. Lifecycle Event
Suspended SUSPENDED cmp_network_token.suspended A network token has been suspended by the issuing card network (Mastercard, Visa, etc). Status Update
Activated ACTIVATED cmp_network_token.activated A network token has been activated following a suspension. Status Update
Deleted DELETED cmp_network_token.deleted A network token has been deleted via the API. Status Update
Provisioned ACTIVE cmp_network_token.provisioned A network token has been provisioned. Provisioning
Failed FAILED cmp_network_token.provisioning_failed The network token was not provisioned (provisioning failed). Failed Provisioning

Network Token Expiration

  • There is no network token expiration event notification from card networks. Instead, networks automatically renew the network token expiration date when applicable.
  • Network Token expiration is managed by card networks and is independent of the PAN expiration.
  • Visa: Network Token expiration typically matches the PAN expiration.
  • Mastercard: Network Tokens generally expire 36 months after provisioning, meaning they may remain active even if the PAN has expired.
  • Network Tokens do not automatically re-provision upon expiration.
  • Transactions will fail if either the network token or PAN is expired.
  • When a network token expires, you can check for network token updates via account updater using the cardID OR subscribe cards for account updater with VGS to automatically receive card updates.

Key Actions:

  • Monitor both PAN and network token expiration dates.
  • Implement logic to handle transaction failures due to expiration.
  • Use account updater to keep card details up to date.

Network Token Deletion

  • Network Tokens remain active unless explicitly deleted by the issuer.
  • The cmp_network_token.deleted event indicates that an network token has been removed.
  • Currently, merchants cannot delete network tokenss via the Card Management Platform (CMP), but this functionality will be introduced soon.

Provisioning Failure Reason Codes:

Reason Code Reason Text Customer Retry VGS Retry
provisioning_failed Invalid payment instrument or data associated with the payment instrument Yes No
card_not_allowed Card cannot be used for tokenization at this moment. Please try again later Yes No
card_not_allowed The requested action is not allowed for a given PAN. This card is valid but cannot be used for tokenization. No No
declined This card is not eligible for tokenization at this moment with the Network; Retry at a later time. Yes No
declined No further operations are allowed. Contact bank No No
service_unavailable Downstream service unavailable; retry later No Yes
rejected This card is not eligible for tokenization at this moment with the Network; Retry later. Yes No

CMP includes these reason codes and texts from the network in both the API response and the webhook notifications.

Retries

  • Customer Retries (Yes): If this column is marked "Yes", the customer can resend the network token provisioning request using the cardID and the dedicated network token endpoint. Currently, if the POST request is made again using the same card object, a new cardID will be generated, and the system will attempt to provision network token with the networks again for this new cardID. This behavior will continue until Duplicate Detection is added in CMP (coming soon).
  • VGS Retries (Yes): If this column is marked "Yes", VGS will automatically retry network token provisioning up to 3 times within a 12-hour window. If all three attempts fail, VGS will stop retrying, and no customer notification will be sent.

CMP aggregates all network token notifications into the cmp_network_token.updated event. Unlike account updater, which emits distinct event types for each notification, network token events share a common structure. The state field denotes the specific notification type, and the event field remains cmp_network_token.updated.

  • Lifecycle events: CARD_UPDATED
  • Status updates: SUSPENDED, ACTIVATED, DELETED

Note: The 'card_first8' field will be returned in the card notifications only for Visa and Mastercard cards.

Payload
descriptionstringRequired
eventstringRequired
fingerprintstringRequired
groupingstringRequired
idstringRequired
integration_idstringRequired
occurrenceintegerRequired
org_idstringRequired
scopestringRequired
summarystringRequired
tenantstringRequired
timestampstringRequired
Responses
200

Return a 200 status to indicate that the data was received successfully.

Payload

{
  "description": "Network token updated",
  "details": {
    "card_id": "CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No",
    "card_bin": "545503",
    "card_expiration_month": "4",
    "card_expiration_year": "2023",
    "card_last4": "6828",
    "card_first8": "54550378",
    "payment_account_reference": "V0013545834930585516258022674",
    "created_at": "2024-08-28T23:11:00.013532771Z",
    "network_token_expiration_month": "2",
    "network_token_expiration_year": "2023",
    "network_token_id": "NTKNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No",
    "network_token_bin": "123456",
    "network_token_last4": "1234",
    "state": "CARD_UPDATED",
    "tenant_id": "ACT9eeBkBsxXe9wWJkQdpG2kC",
    "updated_at": "2024-08-28T23:11:00.013532771Z",
    "reason_code": "cmp_card_updated",
    "reason_text": "The network has updated the card metadata."
  },
  "event": "cmp_network_token.updated",
  "fingerprint": "f438b385c1ed2c40a9379fcea75b3a40eec865fa3c9d0812ab212d45e5a84eca",
  "grouping": "every_single",
  "id": "7a4a31dd-8494-4400-8c19-0e88b814089c",
  "integration_id": "INvwsS1BGFs6ZjQ2eCiv9JV1",
  "occurrence": 1,
  "org_id": "ACmAx8rXF16qPupyWzyLM6v9",
  "producer": {
    "application_name": "calm-api",
    "application_protocol": "http"
  },
  "scope": "vault",
  "summary": "A Network Token for card id 'CRDNDuSxRXmWMdGkxaaPB8Q7ZVZnQTXJnebcjFD9T9DyK5EiP2No' has been updated\n",
  "tenant": "ACT9eeBkBsxXe9wWJkQdpG2kC",
  "timestamp": "2024-07-18T06:23:48.711Z"
}
PreviousAccount Updater Events