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, or a Delete was triggered from the issuing bank | 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.
- When Duplicate Card Detection is enabled, resending the same card object via POST will return a 303 (no new cardID). Customers must use the existing cardID with the dedicated network token endpoint.
- When Duplicate Card Detection is disabled, resending the same card object via POST will generate a new cardID.
- In onCreate enrollment type/mode, CMP will retry provisioning automatically for the new cardID.
- In manual enrollment type/mode, the customer must resend the request using the new cardID.
- Find more information on Duplicate Card Detection here.
- When Duplicate Card Detection is disabled, resending the same card object via POST will generate a new cardID.
- 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.
No content
Payload
Last updated