Tokenization Control [Beta]

Learn how to control tokenizations with Lithic.

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

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"
}
typeThe type of responder. Currently only TOKENIZATION_DECISIONING is supported. String
urlURL that decisioning requests will be sent. String

Sample Response

{"enrolled": True}
enrolledIndication of whether the decisioning endpoint was enrolled successfully. Boolean

Delete a Tokenization Decisioning Responder

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

Sample Request

{"type": "TOKENIZATION_DECISIONING"}
typeThe type of responder. Currently only TOKENIZATION_DECISIONING is supported. String

Sample Response

{}

Get a Tokenization Decisioning Responder

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

Sample Request

{"type": "TOKENIZATION_DECISIONING"}
typeIndicates the type of decisioning responder to be retrieved.

Sample Response

{"url": "https://example.com"}
urlURL that is currently registered for the specified responder type. String.

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}
secretHMAC key for securing tokenization decisioning requests. String.

Rotate Tokenization Decision Secret

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

Sample Request

{}

Sample Response

{"secret": secret}
secretHMAC key for securing tokenization decisioning requests. String

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. Can be APPROVED, REQUIRE_ADDITIONAL_AUTHENTICATION, or DECLINED.

Device Schema

imeiThe IMEI number of the device being provisioned.
storage_technologyThe architecture or technology used for token storage.
locationLatitude and longitude where the device the consumer is attempting to authorize is located.
ip_addressThe 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.

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.
  1. 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"
    }
}
event_typeEvent type. See Event Types for a full list of events.
createdAn RFC 3339 timestamp for when the auth code was sent.
account_tokenGlobally unique identifier for the Lithic account that the card will be associated with. String. Permitted values: 36-digit version 4 UUID (including hyphens).
card_tokenGlobally unique identifier for the card. String. Permitted values: 36-digit version 4 UUID (including hyphens).
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). String.
authentication_codeCode to be passed to end user to complete digital wallet authentication process. String.

Activation Method Schema

typeThe type of activation method the user selected in their digital wallet to receive their authentication code. Possible values are: TEXT_TO_CARDHOLDER_NUMBER or EMAIL_TO_CARDHOLDER_ADDRESS.
valueThe value of the activation method corresponding to the type. This is either the user's phone number or their email address. This String.