Tokenization Decisioning

Learn how to decision tokenizations with Lithic.

See About Digital Wallets for a broader overview of digital wallet tokenizations.

👍

Customer Tokenization Decisioning is only available for Mastercard programs and for Digital Wallet Tokens. It is not available for Merchant Tokens.

Lithic offers two ways to decision on digital wallet tokenizations:

  1. Lithic decisions on your behalf, generally aligned with the wallets’ recommendations, or
  2. You decide with a tokenization decisioning responder, similar to decisioning for card transactions with Auth Stream Access.

Being able to accurately decision on tokenization is important for two reasons:

  1. Fraud on digital wallet cards is generally not disputable with the networks, as digital wallet transactions are categorized as Card Present. This means stopping fraudulent tokenizations can prevent unrecoverable fraud.
  2. False positives, in which a non-fraudulent user is blocked from tokenizing, can frustrate end users.

Tokenization Decisioning by Lithic

For customers who prefer simpler implementations, Lithic can decision on tokenizations on your behalf. Note that for Lithic to decision on tokenizations, you must be enrolling accountholders so that Lithic has the information on file to authenticate your end users when the wallets require two-factor authentication.

Customer Tokenization Decisioning

Note: Customer Tokenization Decisioning is currently only available for Mastercard.

Customers who want to decision on tokenizations themselves should set up a tokenization decisioning responder to build their own logic around who should or should not be approved to tokenize cards. Below are the possible outcomes of tokenization decisioning. Please note that Lithic will not allow a more permissive tokenization decision than what the wallets require. For example, if you respond to a request with APPROVE even though the wallets recommended REQUIRE_AUTHENTICATION, Lithic will fallback to our own tokenization logic and likely adhere to the wallets' recommendation. Note that if a card is in the CLOSED state, we will always decline the request and never send a request to your tokenization decisioning responder.

Setting Up a Tokenization Decisioning Responder

To use Tokenization Decisioning, you'll first have to set up a responder to which we'll send Tokenization Decisioning Requests. This responder should reply to our requests with a Tokenization Decisioning Response. Use the Enroll a Responder Endpoint with type TOKENIZATION_DECISIONING to set up your responder for this purpose.

To delete an existing responder, use the Disenroll a Responder Endpoint at any time. To determine whether you have an enrolled endpoint or to retrieve the URL for your responder endpoint, use the Check the Status of a Responder Endpoint.

Tokenization Decisioning HMAC Secrets

Tokenization decisioning requests use the same HMAC functionality as Lithic's Events API for security. You'll need to sign your responses with your HMAC secret. See the Events API's Verifying Webhooks documentation for more information.

To retrieve your secret key for tokenization decisioning, use the Retrieve the Tokenization Decisioning HMAC Secret Key endpoint. To rotate or generate a new secret key, use the Rotate the Tokenization Decisioning HMAC Secret Key endpoint. Note that the prior secret key will be deactivated after 24 hours from a successful API call.

Tokenization Decisioning Request

Once you've set up your tokenization decisioning responder, we'll send you a decisioning request for each digital wallet tokenization very similar to the Tokenization Approval Webhook. They are identical except the Tokenization Decisioning Request will not have the customer_tokenization_decision field; it will be populated after your endpoint responds to the request and then sent in the Tokenization Approval Webhook.

Sample Request:

{
  "event_type": "digital_wallet.tokenization_approval_request",
  "created": "String",
  "account_token": "String",
  "card_token": "String",
  "tokenization_source": "String",
  "tokenization_token": "String",
  "issuer_decision": "APPROVED/VERIFICATION_REQUIRED/DENIED",
  "digital_wallet_token_metadata": {
    "status": "PENDING",
    "token_requestor_id": "String",
    "token_requestor_name": "String",
    "payment_app_instance_id": "String",
    "payment_account_info": {
      "payment_account_reference": "String",
      "pan_unique_reference": "String",
      "token_unique_reference": "String",
      "account_holder_data": {
        "phone_number": "15555555555"
      },
    },
  },
  "wallet_decisioning_info": {
    "account_score": "4",
    "device_score": "5",
    "recommendation_reasons": null,
    "recommended_decision": "APPROVED"
  },
  "device": {
    "imei": "TBD",
    "location": "String",
    "ip_address": "111.111.111"
  }
}
event_typeEvent type. See Event Types for a full list of events.
createdAn RFC 3339 timestamp for when the card was created.
account_tokenThe token of the account under which the tokenization is occurring.
card_tokenThe token of the card being tokenized.
tokenization_sourceThe source of the tokenization. Possible values are: MANUAL_PROVISION, PUSH_PROVISION, ACCOUNT_ON_FILE, and UNKNOWN.
tokenization_tokenThe unique ID of the tokenization attempt. Generated for each tokenization attempt made (i.e., each attempt by a single PAN generates multiple IDs).
issuer_decisionLithic's decision on the tokenization. Possible values are: APPROVED, VERIFICATION_REQUIRED, or DENIED

Digital Wallet Token Metadata Schema

statusThe current status of the tokenization attempt. Can be PENDING or DECLINED.
token_requestor_idID representing the party requesting tokenization (this includes merchant tokenizations).
token_requestor_nameReadable name representing the party requesting tokenization. Can be APPLE_PAY, ANDROID_PAY, or SAMSUNG_PAY.
payment_app_instance_idID representing the payment app instance.
payment_account_referenceReference for the unique funding PAN; remains the same across tokens derived from that PAN.
pan_unique_referenceMastercard-specific PAN reference.
token_unique_referenceA unique reference used to identify the token for the duration of its lifetime.
phone numberPhone number associated with the funding account being tokenized.

Wallet Decisioning Schema

account_scoreScore of 1 (poor) to 5 (excellent) given to the Wallet's account to rate their relationship with their customer or account holder.
device_scoreScore of 1 (poor) to 5 (excellent) given to the device by the Wallet Provider to indicate the trustworthiness of the device.
recommendation_reasonsList of reasons provided to the Wallet Provider on how the recommended decision was reached. If no reasons were provided, value will be null.
recommended_decisionRecommended decision from the Wallet Provider. Possible values are: APPROVED, REQUIRE_ADDITIONAL_AUTHENTICATION, or DECLINED.

Device Schema

imei (optional)The IMEI number of the device being provisioned.
storage_technology (optional)The architecture or technology used for token storage.
location (optional)Latitude and longitude where the device the consumer is attempting to authorize is located.
ip_address (optional)The IP of the device initiating the request.

Tokenization Decisioning Response

Your responder should be set up to respond to Lithic's Tokenization Decisioning Request with the below response. As part of decisioning, you must share users' authentication information to pass to the wallets. The wallets then display this information to end users to select how they want to authenticate (for a code to be sent to j***[email protected], for example). This also ensures 2FA codes sent by Lithic are sent to the most recent email/phone number on file; Lithic deletes this user info 30 minutes after receipt.

Customers enabling their end users to authenticate via mobile app must pass the name of the mobile app that will be opened by the wallet for user authentication. Please note that at least two methods must be passed for your decision to be accepted if your decision is AUTHENTICATE.

Sample Response:

{
  "tokenization_decision": "APPROVE" | "AUTHENTICATE" | "DECLINE",
  "phone_number": "+15558675309",
  "email": "[email protected]",
  "mobile_application_name": "Wells Fargo"
}
tokenization_decisionYour decision on whether to Approve, Authenticate, or Decline the tokenization request.
phone_numberPhone number of the end user attempting a tokenization. Lithic must pass this to the card networks to pass to the wallets to display for the user as they select an authentication option in their digital wallet. Lithic will always default to using this value for authentication over the accountholder information on file.
String. E.164 format without hyphens. For example, "+12124007676" for a US phone number.
emailEmail address of the end user attempting a tokenization to be used for authentication. Lithic must pass this to the card networks to pass to the wallets to display for the user as they select an authentication option in their digital wallet. Lithic will always default to using this value for authentication over the accountholder information on file.
String. Permitted values: Valid email address. For example, "[email protected]".
mobile_application_nameName of the mobile application that the digital wallet will open for the end user to complete authentication. String. For example, "Wells Fargo."

Response Guidelines

If we do not receive a tokenization decisioning response from you in 2.5 seconds, we will decision on the tokenization on your behalf.