Skip to main content

Request Handling

Payment networks and third-party wallets may imply the additional requirements for issuer that require to keep the trace of incoming requests and handle them accordingly or trigger specific events.

For example, several third-party wallets have the following requirements:

  1. Issuers must deliver a notification confirming a successful provisioning activation using a tenured channel.
  2. The Card Issuer shall send an In-App, SMS, or Email notification to customers who abandon provisioning within 24 hours
  3. The Card Issuer shall send an In-App, SMS, or Email notification to customers who abandon provisioning within 24 hours

Token notification API (Issuer responsibility)​

The token notification API is being used at several points during the digitization process and post digitization. To differentiate the context of these different situations use the reasonCode to explain when the token notification happens. The different reason codes for token notification are the following:

  • CREATED
  • ACTIVATED
  • SUSPENDED
  • RESUMED
  • DELETED
  • PAN_UPDATE
  • EXP_DATE_UPDATED
  • RENEWED
  • DEVICE_ BINDING_APPROVED
  • DEVICE_BINDING_REMOVED
  • PROVISIONING_DECLINED
  • DEVICE_BINDING_DECLINED

The token notification API is the most informative API in terms of explaining what is happening to a certain token. Centering the different request handling logic around this API call is recommended.

Abandoned provisioning​

Third-party wallets may have the requirements to handle the abandoned provisioning accordingly, e.g. notify and remind customer that he started provisioning but didn’t finish it within 24 hours or to delete the token if provisioning is abandoned for more than 30 days.

Issuers must handle and store the incoming requests from Pre-Digitization API OBO accordingly to implement the requirements for abandoned provisioning. Stored incoming requests must have the timestamp that defines when they were received.

Provisioning can be considered as completed when a “Token Notification” request with reasonCode “ACTIVATED” is received from MeaWallet Pre-Digitization API OBO.

To determine the abandoned provisioning issuer must define when it was started. This can be done based on the “Token Notification ” request with the reasonCode “CREATED”. Until a new “Token Notification” request with either the reasonCode “ACTIVATED” or “PROVISIONING DECLINED” is received, the process can be considered as incomplete. To understand whether the different calls belong to the same provisioning attempt the Issuer can either use tokenUniqueReference or cardInfo.

Successful provisioning​​

Issuers must automatically notify cardholders about the successful provisioning into the third-party wallet. This requirement only applies to the third-party wallets and must not be implemented for STATIC token types as Card-On-File or E-commerce purpose tokens. STATIC token types must be ignored because token provisioning may be requested in the background without cardholder notice, e.g. overnight PCI card-on-file tokens conversion to the network card/token-on-file tokens by merchant or payment service provider.

"Token Notification" with reason_code “ACTIVATED” request received by the issuer is the foreseen trigger action for cardholder notification about the successful token provisioning.

Token details storage​

Issuers may decide to accumulate the received token details for history, browsing and reporting purposes. “Token notification” requests contain the available token details that the issuer may structure and store.