Token updated event

This webhook event is triggered when a payment token has been updated in the system, indicating that one or more attributes of the token, such as expiry date, card number, or account holder information have been modified. The event provides the updated token identifier and the associated shopper reference, allowing systems to keep tokenized payment data current and maintain accurate token lifecycle management.

Webhook Example

{
    "checkoutReference": "e6j0wmay25tm6a10z5j86o1j42pggpwkur6u1f8941c43d6k58",
    "payfacReference": "164EF8478A748",
    "merchantReference": "w53xg1e8",
    "amount": "108000",
    "currency": "ISK",
    "reason": "CardChanged",
    "success": "true",
    "hmacSignature": "eVu7uR8wcEiMxa5s8lSX/YYvU5LkshLdOSccUZ4M//0=",
    "additionalData": {
        "eventType": "TokenUpdated",
        "token": "164EF8478A748",
        "shopperReference": "xoj0qfx9S7G7fj7byhVu6Tot6G9vjvvP",
        "cardNumber": "41545845****6478",
        "cardSummary": "6478",
        "cardExpiryDate": "11/2029",
        "cardUsage": "Credit",
        "paymentMethod": "VI",
    }
}

info

HMAC key: 297d288c4ef7e65d317dbb14dcbe16d054976f25328bc387

Headers

In the Authorization header, we will set the matching Api key for your webhook.

Fields

You will always get these fields.

Field	Type	Description
checkoutReference	nullable string	Unique identifier for the payment that was done through a checkout.
payfacReference	string	The reference of the payment that triggered the webhook.
merchantReference	nullable string	The identifier for the payment provided by you, the merchant, allowing for correlation with the merchant’s system.
amount	string	The payment amount in the minor currency unit.
currency	string	The three-letter ISO currency code.
reason	nullable string	A field that provides additional context.
success	string	Indicates the action status (true/false).
hmacSignature	string	A cryptographic signature generated using a secret, enabling verification of the message authenticity and ensuring it hasn’t been tampered with.
additionalData	object	An object for the additional details included in the event.

Additional Data Fields

Fields you will get depend on the event type of the webhook.

Field	Type	Description
eventType	string	A string representing the type of event that occurred.
token	string	The identifier of the payment token that has been updated.
shopperReference	string	The shopper reference identifier associated with the updated token.
cardNumber	string	A partially masked PAN.
cardSummary	string	Last 4 digits of PAN.
cardExpiryDate	string	Card expiration date in "MM/yyyy" format.
cardUsage	string	The source of funds used for a authorization.
paymentMethod	string	The payment method used in the authorization.

Card Update Status

The reason field in the webhook indicates what type of update occurred for the token. This helps you understand what changed and how to handle the update in your system.

Action Required

For statuses CloseAccount, ContactCardAccountHolder, and Unknown, the card details were not actually updated. You should take appropriate action such as disabling the token and requesting new payment information from the cardholder.

The following statuses indicate the type of card update:

Status	Description	Card Updated	Webhook Data Received
CardChanged	Indicates that a new card number has been issued to replace the previous one. The stored token will now be associated with the updated card number.	Yes	Updated token with new cardNumber and cardSummary
CardExpiryChanged	The expiration date of the card has been updated while the card number stays unchanged. This commonly occurs when a card is renewed.	Yes	Updated token with new cardExpiryDate
CloseAccount	The issuing bank has deactivated this card and it cannot be used for transactions. Card information remains in the system but must be manually disabled. Request updated payment details from the customer.	No	Token identifier and shopper reference, but card details remain unchanged
ContactCardAccountHolder	(Visa only) Updated card information exists but is not accessible through the Account Updater service. Direct communication with the cardholder is necessary to retrieve the new card details.	No	Token identifier and shopper reference, but card details remain unchanged
Unknown	(Mastercard only) The update status could not be determined. This often occurs when the card information is temporarily unavailable in Mastercard's system and may resolve itself.	No	Token identifier and shopper reference, but card details remain unchanged