Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
Tokenization

Tokenization Decisioning Request

Tokenization Customer Decisioning Request. Use tokenization.approval_request for notification webhooks.

postWebhookdigital_wallet.tokenization_approval_request

Headers

webhook-idstring uuid

Webhook ID

webhook-timestampinteger

Unix timestamp used for HMAC verification

webhook-signaturestring

A list of HMAC signatures encoded in Base64 and separated by spaces. Can contain multiple HMAC signatures as a result of key rotation.

Payload

account_tokenstring required

Unique identifier for the user tokenizing a card

card_tokenstring required

Unique identifier for the card being tokenized

createdstring date-time required

Indicate when the request was received from Mastercard or Visa

issuer_decision'APPROVED' | 'DENIED' | 'VERIFICATION_REQUIRED' required

Whether Lithic decisioned on the token, and if so, what the decision was. APPROVED/VERIFICATION_REQUIRED/DENIED.

tokenization_channel'DIGITAL_WALLET' | 'MERCHANT' required

The channel through which the tokenization was made.

tokenization_source'ACCOUNT_ON_FILE' | 'CONTACTLESS_TAP' | 'MANUAL_PROVISION' | 'PUSH_PROVISION' | 'TOKEN' | 'UNKNOWN'

The source of the tokenization.

tokenization_tokenstring required

Unique identifier for the digital wallet token attempt

event_type'digital_wallet.tokenization_approval_request' required

The name of this event

tokenization_decline_reasonsTokenizationDeclineReason[]

List of reasons why the tokenization was declined. Only populated in webhook events, not in the initial decisioning request

tokenization_tfa_reasonsTokenizationTfaReason[]

List of reasons why two-factor authentication was required. Only populated in webhook events, not in the initial decisioning request

Example payload

{
  "account_token": "00000000-0000-0000-0000-000000000002",
  "card_token": "00000000-0000-0000-0000-000000000001",
  "created": "2023-09-18T12:34:56Z",
  "device": {
    "imei": "123456789012345",
    "ip_address": "1.1.1.1",
    "location": "37.3860517/-122.0838511"
  },
  "digital_wallet_token_metadata": {
    "payment_account_info": {
      "account_holder_data": {
        "phone_number": "+15555555555"
      },
      "pan_unique_reference": "pan_unique_ref_1234567890123456789012345678",
      "payment_account_reference": "ref_1234567890123456789012",
      "token_unique_reference": "token_unique_ref_1234567890123456789012345678"
    },
    "payment_app_instance_id": "app_instance_123456789012345678901234567890",
    "status": "Pending",
    "token_requestor_id": "12345678901",
    "token_requestor_name": "APPLE_PAY"
  },
  "event_type": "digital_wallet.tokenization_approval_request",
  "issuer_decision": "APPROVED",
  "tokenization_channel": "DIGITAL_WALLET",
  "tokenization_source": "PUSH_PROVISION",
  "tokenization_token": "tok_1234567890abcdef",
  "wallet_decisioning_info": {
    "account_score": "100",
    "device_score": "100",
    "recommendation_reasons": [
      "Reason1"
    ],
    "recommended_decision": "Decision1"
  }
}

Response

Return a HTTP 200 status to indicate that the Tokenization Responder was able to handle the request.

tokenization_decision'APPROVE' | 'AUTHENTICATE' | 'DECLINE' required

The decision for tokenization

phone_numberstring required

Phone 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 account holder information on file. E.164 format without hyphens. For example, "+15555555555" for a US phone number.

emailstring email required

Email 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 account holder information on file. Permitted values: Valid email address. For example, "johnny@appleseed.com".

mobile_application_namestring required

Name of the mobile application that the digital wallet will open for the end user to complete authentication. For example, "Wells Fargo".

Example response

{
  "tokenization_decision": "AUTHENTICATE",
  "phone_number": "+15555555555",
  "email": "test@example.com",
  "mobile_application_name": "Wells Fargo"
}