--- id: customer-tokens title: "Webhooks for customer tokens" sidebar_label: "Customer Tokens" hide_title: true description: "Webhooks related to customer tokens" --- import Ingress from "../../src/components/ingress/ingress.react"; These webhooks notify you when a customer token changes status, for example when it becomes active, is canceled or is revoked. ## Events Each event below corresponds to a customer token transitioning into a new status. The event type matches the new status of the token. | Event type | Triggered when | | --------------------------------- | --------------------------------------- | | `walley:customer-token:active` | A customer token becomes active. | | `walley:customer-token:pending` | A customer token is pending activation. | | `walley:customer-token:cancelled` | A customer token is canceled. | | `walley:customer-token:denied` | A customer token is denied. | | `walley:customer-token:revoked` | A customer token is revoked. | | `walley:customer-token:suspended` | A customer token is suspended. | All customer token webhooks share the same payload structure. The `Type` property reflects the new status, and `Payload.PreviousStatus` contains the status the token had before the change. The token status is a computed value derived from whether the token has been canceled, whether it is suspended, and the buyer's approval state. An event is emitted whenever this computed status changes after an update, so the webhook always reflects a genuine transition rather than a repeated notification of the same status. ### walley:customer-token:active This webhook is triggered whenever a customer token becomes active and can be used for [authorizations](/docs/checkout/tokenization/authorization). A token is `Active` when it has not been canceled, is not suspended, and the buyer's approval is either not required or has been approved. A transition into `Active` typically occurs when: - A previously `Suspended` token is re-activated, for example when a payment provider consent (such as Swish) changes back to active after being pending. `Source` is `PaymentProvider`. - A `Pending` token's buyer is approved by Walley's business profile system. `Source` is `WalleyBusiness`. ```json { "Type": "walley:customer-token:active", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Pending", "Source": "WalleyBusiness" } } ``` ### walley:customer-token:pending This webhook is triggered whenever a customer token is awaiting buyer approval from Walley's business profile system. A `Pending` token cannot yet be used for payments. A token becomes `Pending` when it is registered for a buyer whose approval is required, for example a business customer that needs a credit check or approval. The initial registration itself does not emit an event because there is no previous status to transition from, but any later change back to `Pending` does. ```json { "Type": "walley:customer-token:pending", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Active", "Source": "WalleyBusiness" } } ``` ### walley:customer-token:cancelled This webhook is triggered whenever a customer token is permanently canceled and can no longer be used for payments. When a token is canceled it is scheduled for removal after a 90-day retention period. A transition into `Cancelled` occurs when: - A merchant cancels the token via the [cancel endpoint](/docs/checkout/tokenization/cancel-token). `Source` is `Merchant`. - A payment provider signals that the underlying agreement or consent has been deleted, for example when a Swish consent is deleted by the payer or has expired. `Source` is `PaymentProvider`. ```json { "Type": "walley:customer-token:cancelled", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Active", "Source": "Merchant" } } ``` ### walley:customer-token:denied This webhook is triggered whenever the buyer has been denied by Walley's business profile system. A denied token cannot be used, and the token is scheduled for removal after a 90-day retention period. A transition into `Denied` occurs when Walley's business profile system denies the buyer for the buyer and merchant combination; all matching tokens are updated. `Source` is `WalleyBusiness`. ```json { "Type": "walley:customer-token:denied", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Pending", "Source": "WalleyBusiness" } } ``` ### walley:customer-token:revoked This webhook is triggered whenever the buyer's approval has been revoked by Walley's business profile system, for example because the buyer no longer meets ongoing requirements. A revoked token cannot be used, and the token is scheduled for removal after a 90-day retention period. A transition into `Revoked` occurs when Walley's business profile system revokes the buyer for the buyer and merchant combination; all matching tokens are updated. `Source` is `WalleyBusiness`. ```json { "Type": "walley:customer-token:revoked", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Active", "Source": "WalleyBusiness" } } ``` ### walley:customer-token:suspended This webhook is triggered whenever a customer token becomes temporarily unusable because the underlying payment provider agreement is in a transitional state. Unlike the canceled, denied and revoked states, a suspended token has no retention period and remains indefinitely until it is either re-activated or canceled. A transition into `Suspended` occurs when a payment provider consent enters a pending state, for example when a Swish consent is being renewed or the payer needs to re-confirm it. `Source` is `PaymentProvider`. A suspended token can later return to `Active` if the consent becomes active again. ```json { "Type": "walley:customer-token:suspended", "Timestamp": "2026-06-15T05:06:45.0324162+00:00", "Payload": { "CustomerToken": "32c5ee34-3de6-411f-a326-5dd1604654f0", "PreviousStatus": "Active", "Source": "PaymentProvider" } } ``` ## Payload | Property | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------- | | `Type` | string | The webhook event type. One of the event types listed in the [Events](#events) table. | | `Timestamp` | date | ISO 8601 date-time of when the status change occurred. | | `Payload.CustomerToken` | Guid | The unique identifier of the customer token. See [Getting token details](/docs/checkout/tokenization/token-details). | | `Payload.PreviousStatus` | string | The status the token had before this change. One of `Active`, `Pending`, `Cancelled`, `Denied`, `Revoked` or `Suspended`. | | `Payload.Source` | string | What initiated the status change. See [Source values](#source-values). | ### Source values | Value | Meaning | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | | `PaymentProvider` | The change was triggered by an external payment provider callback, for example a Swish consent status update. | | `Merchant` | The change was initiated by the merchant, for example cancelling the token via the API. | | `WalleyBusiness` | The change was triggered by Walley's internal business profile system, for example buyer approval, denial or revocation. |