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

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.

Setting Up a Tokenization Decisioning Responder

To use Tokenization Control, 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.

Create a tokenization decisioning responder

POST https://api.lithic.com/v1/responder_endpoints

Sample Request

{
  "type": "TOKENIZATION_DECISIONING",
  "url": "https://example.com"
}

Sample Response

{"enrolled": True}

Delete a Tokenization Decisioning Responder

DELETE https://api.lithic.com/v1/responder_endpoints

Sample Request

{"type": "TOKENIZATION_DECISIONING"}

Sample Response

{}

Get a Tokenization Decisioning Responder

GET https://api.lithic.com/v1/responder_endpoints

Sample Request

{"type": "TOKENIZATION_DECISIONING"}

Sample Response

{"url": "https://example.com"}

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.

Get Tokenization Decision Secret

GET https://api.lithic.com/v1/tokenization_decisioning/secret

Sample Request

{}

Sample Response

{"secret": secret}

Rotate Tokenization Decision Secret

POST https://api.lithic.com/v1/tokenization_decisioning/secret/rotate

Sample Request

{}

Sample Response

{"secret": secret}

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"
  }
}

Digital Wallet Token Metadata Schema

Wallet Decisioning Schema

Device Schema

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"
}

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.

Sending Cardholders 2FA Codes

See Cardholder Authentication for an overview of two-factor authentication for digital wallets. The generation of a 2FA code is triggered when either the wallet or you decide (if using self-serve tokenization decisioning above) to authenticate the end user trying to tokenize their card. Note that when Apple or Google pass a recommendation_decision of REQUIRE_ADDITIONAL_AUTHENTICATION, Lithic must either trigger 2FA or decline the tokenization per the wallets’ requirements.

Lithic offers two ways to send a two-factor authentication code to end users:

1. Lithic sends the 2FA code on your behalf. We will send the user a message via text or email using the information on file for enrolled accountholders. Speak to your implementation manager about how to set this up.

2. You send the 2FA code to end users yourself. You may want to customize your messaging and/or send all messages from a single, consistent email address or phone number. If you want to send 2FA codes yourself, register an event subscription URL to subscribe to events of type digital_wallet.tokenization_auth_code. See Digital Wallet Tokenization Auth Code.

Digital Wallet Tokenization Auth Code

Lithic also enables customers to deliver authentication codes to end users themselves. This webhook will only be sent to customers authenticating their end users via email or phone; this code will not be sent for users authenticating via mobile app. Lithic will webhook you the two-factor authentication code using event_type: digital_wallet.tokenization_two_factor_authentication_code. Note that to receive these webhooks, you'll need to subscribe to this event type using our Events API.

{
  "event_type": "digital_wallet.tokenization_two_factor_authentication_code",
  "created": "String",
  "account_token": "String",
  "card_token": "String",
  "tokenization_token": "String",
  "authentication_code": "String",
    "activation_method": {
    "type": "String",
    "value": "String"
    }
}

Activation Method Schema