Handle enrollment failures

Enrollment can fail after the end user starts provisioning a card.

When this happens, the token requestor (wallet provider) or the payment network TSP can delete the token.

What the issuer backend receives

Tokenization Service notifies the issuer backend using notifyVirtualCardChange.

For enrollment failures that result in token deletion, action is typically:

• DELETE (token deleted on the payment network TSP)

• DELETE_FROM_APP (token deleted in the wallet application, MDES only)

notifyVirtualCardChange also includes:

• x-correlation-id (HTTP header) to link the enrollment session.

• virtualCardId and issuerCardRefId to identify the token and card.

• source to indicate who initiated the change (WALLET, TSP, or ISSUER).

Example request body (simplified)

{
  "issuerCardRefId": "string",
  "virtualCardId": "string",
  "walletProviderId": "APPLE_PAY",
  "isPrimary": true,
  "action": "DELETE",
  "source": "TSP"
}

How to handle enrollment failures

Handle notifyVirtualCardChange idempotently. You can receive duplicates or late callbacks.

When action indicates deletion:

1. Mark the token as deleted in the issuer backend.

2. Stop any pending step-up authentication for this enrollment.

3. Allow the end user to restart enrollment.

notifyVirtualCardChange is used for more than enrollment failures. It is also used for state changes like ACTIVATE, SUSPEND, and RESUME.

Related documentation

• Token state update by the wallet

• Outbound (to issuer)