---
title: "Tokenization Decisioning Request"
method: POST
path: "digital_wallet.tokenization_approval_request"
tags: ["Tokenization"]
---

# Tokenization Decisioning Request

`POST digital_wallet.tokenization_approval_request` (webhook)

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

## Headers

- `webhook-id` string, uuid
- `webhook-timestamp` integer
- `webhook-signature` string

## Payload

- DigitalWalletTokenizationApprovalRequest — Base properties shared by both tokenization decisioning requests (with response) and without
  - `account_token` string, required — Unique identifier for the user tokenizing a card
  - `card_token` string, required — Unique identifier for the card being tokenized
  - `created` string, date-time, required — Indicate when the request was received from Mastercard or Visa
  - `device` Device
    - `imei` string, nullable, required — The IMEI number of the device being provisioned. For Amex, this field contains device ID instead as IMEI is not provided
    - `ip_address` string, nullable, required — The IP address of the device initiating the request
    - `location` string, nullable, required — Latitude and longitude where the device is located during the authorization attempt
  - `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_token` string, required — Unique identifier for the digital wallet token attempt
  - `wallet_decisioning_info` WalletDecisioningInfo, required
    - `account_score` string, nullable, required — Score given to the account by the Wallet Provider
    - `device_score` string, nullable, required — Score given to the device by the Wallet Provider
    - `recommendation_reasons` string[], nullable — Reasons provided to the Wallet Provider on how the recommended decision was reached
    - `recommended_decision` string, nullable, required — The decision recommended by the Wallet Provider
  - `digital_wallet_token_metadata` DigitalWalletTokenMetadata, required — Contains the metadata for the digital wallet being tokenized.
    - `payment_account_info` object, required — Contains the information of the account responsible for the payment.
      - `account_holder_data` object, required — Additional information that can be used to identify the account holder, such as name, address, etc
        - `phone_number` string, nullable — The phone number, may contain country code along with phone number when countryDialInCode is not present
      - `pan_unique_reference` string, nullable — Reference to the PAN that is unique per Wallet Provider
      - `payment_account_reference` string, nullable — The unique account reference assigned to the PAN
      - `token_unique_reference` string, nullable — A unique reference assigned following the allocation of a token used to identify the token for the duration of its lifetime.
    - `payment_app_instance_id` string, nullable — The identifier of the Payment App instance within a device that will be provisioned with a token
    - `status` string, required — The current status of the digital wallet token. Pending or declined.
    - `token_requestor_id` string — The party that requested the digitization
    - `token_requestor_name` 'AMAZON_ONE' | 'ANDROID_PAY' | 'APPLE_PAY' | 'FACEBOOK' | 'FITBIT_PAY' | 'GARMIN_PAY' | 'GOOGLE_PAY' | 'MICROSOFT_PAY' | 'NETFLIX' | 'SAMSUNG_PAY' | 'UNKNOWN' | 'VISA_CHECKOUT' — Human-readable name of the wallet that the token_requestor_id maps to.
  - `customer_tokenization_decision` CustomerTokenizationDecision — Contains the metadata for the customer tokenization decision.
    - `latency` string — Time in ms it took for the customer's URL to respond
    - `outcome` 'APPROVED' | 'DECLINED' | 'ERROR' | 'INVALID_RESPONSE' | 'REQUIRE_ADDITIONAL_AUTHENTICATION' | 'TIMEOUT', required — The outcome of the customer's decision
    - `responder_url` string, required — The customer's subscribed URL
    - `response_code` string — The response code that the customer provided
  - `event_type` 'digital_wallet.tokenization_approval_request', required — The name of this event
  - `tokenization_decline_reasons` TokenizationDeclineReason[] — List of reasons why the tokenization was declined. Only populated in webhook events, not in the initial decisioning request
  - `tokenization_tfa_reasons` TokenizationTfaReason[] — List of reasons why two-factor authentication was required. Only populated in webhook events, not in the initial decisioning request
  - `rule_results` TokenizationRuleResult[] — Results from rules that were evaluated for this tokenization. Only populated in webhook events, not in the initial decisioning request
    - `auth_rule_token` string, uuid, nullable, required — The Auth Rule Token associated with the rule. If this is set to null, then the result was not associated with a customer-configured rule. This may happen in cases where a tokenization is declined or requires TFA due to a Lithic-configured security or compliance rule, for example.
    - `result` 'APPROVED' | 'DECLINED' | 'REQUIRE_TFA' | 'ERROR', required — The result associated with this rule
    - `name` string, nullable, required — The name for the rule, if any was configured
    - `explanation` string, nullable, required — A human-readable explanation outlining the motivation for the rule's result

## Acknowledgement `200`

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

- TokenizationDecisioningResponse — The response payload that a Tokenization Decisioning responder may respond with in response to a request.
  - `tokenization_decision` 'APPROVE' | 'AUTHENTICATE' | 'DECLINE', required — The decision for tokenization
  - `phone_number` string, 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.
  - `email` string, 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_name` string, required — Name of the mobile application that the digital wallet will open for the end user to complete authentication. For example, "Wells Fargo".

---

[API](https://skmtc.net/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.net/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/53ab5d4e2adb/schema)