openapi: 3.1.0
info:
  contact:
    email: support@lithic.com
  description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.

    Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.

    '
  termsOfService: https://lithic.com/legal/terms
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  title: Lithic Developer 3DS API
  version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
  url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: 3DS
paths:
  /v1/three_ds_authentication/simulate:
    post:
      description: 'Simulates a 3DS authentication request from the payment network as if it came from an ACS. If you''re configured for 3DS Customer Decisioning, simulating authentications requires your customer decisioning endpoint to be set up properly (respond with a valid JSON). If the authentication decision is to challenge, ensure that the account holder associated with the card transaction has a valid phone number configured to receive the OTP code via SMS. '
      operationId: postSimulateAuthentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/simulate-authentication-request'
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              schema:
                properties:
                  token:
                    description: Globally unique identifier for the 3DS authentication.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate 3DS authentication
      tags:
      - 3DS
  /v1/three_ds_decisioning/simulate/enter_otp:
    post:
      description: Endpoint for simulating entering OTP into 3DS Challenge UI. A call to [/v1/three_ds_authentication/simulate](https://docs.lithic.com/reference/postsimulateauthentication) that resulted in triggered SMS-OTP challenge must precede. Only a single attempt is supported; upon entering OTP, the challenge is either approved or declined.
      requestBody:
        content:
          application/json:
            example:
              token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              otp: '123456'
            schema:
              properties:
                token:
                  description: A unique token returned as part of a /v1/three_ds_authentication/simulate call that resulted in PENDING_CHALLENGE authentication result.
                  format: uuid
                  type: string
                otp:
                  description: The OTP entered by the cardholder
                  example: '123456'
                  type: string
              required:
              - token
              - otp
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate entering OTP into 3DS Challenge UI
      tags:
      - 3DS
  /v1/three_ds_authentication/{three_ds_authentication_token}:
    get:
      description: Get 3DS Authentication by token
      operationId: getThreeDsAuthenticationByToken
      parameters:
      - description: Globally unique identifier for the 3DS authentication.
        in: path
        name: three_ds_authentication_token
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authentication'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get 3DS authentication
      tags:
      - 3DS
  /v1/three_ds_decisioning/secret:
    get:
      description: 'Retrieve the 3DS Decisioning HMAC secret key. If one does not exist for your program yet, calling this endpoint will create one for you. The headers (which you can use to verify 3DS Decisioning requests) will begin appearing shortly after calling this endpoint for the first time. See [this page](https://docs.lithic.com/docs/3ds-decisioning#3ds-decisioning-hmac-secrets) for more detail about verifying 3DS Decisioning requests.

        '
      operationId: getThreeDsDecisioningSecret
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  secret:
                    description: The 3DS Decisioning HMAC secret
                    example: whsec_1NDsYinMGr951KuDEaj78VtWzlyPaOnwUVagFiWIPJs=
                    type: string
                type: object
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Retrieve the 3DS Decisioning HMAC secret key
      tags:
      - 3DS
  /v1/three_ds_decisioning/secret/rotate:
    post:
      description: 'Generate a new 3DS Decisioning HMAC secret key. The old secret key will be deactivated 24 hours after a successful request to this endpoint. Make a [`GET /three_ds_decisioning/secret`](https://docs.lithic.com/reference/getthreedsdecisioningsecret) request to retrieve the new secret key.

        '
      operationId: rotateThreeDsDecisioningSecret
      responses:
        '204':
          description: We have successfully rotated the secret key.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Rotate the 3DS Decisioning HMAC secret key
      tags:
      - 3DS
  /v1/three_ds_decisioning/challenge_response:
    post:
      description: 'Card program''s response to a 3DS Challenge Request.

        Challenge Request is emitted as a webhook [three_ds_authentication.challenge](https://docs.lithic.com/reference/post_three-ds-authentication-challenge) and your Card Program needs to be configured with Out of Band (OOB) Challenges in order to receive it (see https://docs.lithic.com/docs/3ds-challenge-flow for more information).'
      summary: Respond to a Challenge Request
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/challenge-response'
      responses:
        '200':
          description: Challenge Response was received and forwarded to the ACS
        '400':
          description: Invalid request body
        '404':
          description: The provided token was not found
        '422':
          description: Challenge Response could not be actioned because a response was already set, or the status was updated by the upstream 3DS Service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/challenge-response-unprocessable'
        '500':
          description: Lithic Error
      tags:
      - 3DS
components:
  schemas:
    error:
      type: object
      properties:
        debugging_request_id:
          type: string
          format: uuid
          description: Identifier to help debug an error.
        message:
          type: string
          description: Explanation of error response.
      required:
      - debugging_request_id
      - message
    authentication:
      title: 3DS Authentication object
      type: object
      description: Represents a 3DS authentication
      properties:
        account_type:
          type:
          - string
          - 'null'
          description: Type of account/card that is being used for the transaction. Maps to EMV 3DS field `acctType`.
          enum:
          - CREDIT
          - DEBIT
          - NOT_APPLICABLE
          - null
        additional_data:
          type:
          - object
          - 'null'
          description: Object containing additional data about the 3DS request that is beyond the EMV 3DS standard spec (e.g., specific fields that only certain card networks send but are not required across all 3DS requests).
          properties:
            network_decision:
              type:
              - string
              - 'null'
              description: 'Mastercard only: Indicates whether the network would have considered the authentication request to be low risk or not.'
              enum:
              - LOW_RISK
              - NOT_LOW_RISK
              - null
            network_risk_score:
              type:
              - integer
              - 'null'
              description: 'Mastercard only: Assessment by the network of the authentication risk level, with a higher value indicating a higher amount of risk. Permitted values: Integer between 0-950, in increments of 50.'
          required: []
        app:
          type:
          - object
          - 'null'
          description: Object containing data about the app used in the e-commerce transaction. Present if the channel is 'APP_BASED'.
          properties:
            device_info:
              type:
              - string
              - 'null'
              description: Raw device information - base64-encoded JSON object. Maps to EMV 3DS field `deviceInfo`.
            ip:
              type: string
              description: IP address of the device.
              x-stainless-naming:
                go:
                  property_name: Ip
            platform:
              type:
              - string
              - 'null'
              description: 'Device platform: Android, iOS, Windows, etc.'
            device:
              type:
              - string
              - 'null'
              description: 'Device model: e.g. "Apple iPhone 16".'
            os:
              type:
              - string
              - 'null'
              description: 'Operating System: e.g. "Android 12", "iOS 17.1".'
            locale:
              type:
              - string
              - 'null'
              description: 'Device locale: e.g. "en-US".'
            time_zone:
              type:
              - string
              - 'null'
              description: Time zone offset in minutes between UTC and device local time.
            screen_width:
              type:
              - integer
              - 'null'
              description: Screen width in pixels.
            screen_height:
              type:
              - integer
              - 'null'
              description: Screen height in pixels.
            latitude:
              type:
              - number
              - 'null'
              description: Latitude coordinate of current device location.
              minimum: -90
              maximum: 90
            longitude:
              type:
              - number
              - 'null'
              description: Longitude coordinate of current device location.
              minimum: -180
              maximum: 180
          required: []
        authentication_request_type:
          type:
          - string
          - 'null'
          description: Type of authentication request - i.e., the type of transaction or interaction is causing the merchant to request an authentication. Maps to EMV 3DS field `threeDSRequestorAuthenticationInd`.
          enum:
          - ADD_CARD
          - BILLING_AGREEMENT
          - DELAYED_SHIPMENT
          - EMV_TOKEN_CARDHOLDER_VERIFICATION
          - INSTALLMENT_TRANSACTION
          - MAINTAIN_CARD
          - PAYMENT_TRANSACTION
          - RECURRING_TRANSACTION
          - SPLIT_PAYMENT
          - SPLIT_SHIPMENT
          - null
        authentication_result:
          type:
          - string
          description: Indicates the outcome of the 3DS authentication process.
          enum:
          - DECLINE
          - SUCCESS
          - PENDING_CHALLENGE
          - PENDING_DECISION
        browser:
          type:
          - object
          - 'null'
          description: Object containing data about the browser used in the e-commerce transaction. Present if the channel is 'BROWSER'.
          properties:
            accept_header:
              type:
              - string
              - 'null'
              description: Content of the HTTP accept headers as sent from the cardholder's browser to the 3DS requestor (e.g., merchant or digital wallet).
            ip:
              description: IP address of the browser as returned by the HTTP headers to the 3DS requestor (e.g., merchant or digital wallet). Maps to EMV 3DS field `browserIP`.
              type: string
              nullable: true
              x-stainless-naming:
                go:
                  property_name: Ip
            java_enabled:
              type:
              - boolean
              - 'null'
              description: Indicates whether the cardholder's browser has the ability to execute Java. Maps to EMV 3DS field `browserJavaEnabled`.
            javascript_enabled:
              type:
              - boolean
              - 'null'
              description: Indicates whether the cardholder's browser has the ability to execute JavaScript. Maps to EMV 3DS field `browserJavascriptEnabled`.
            language:
              type:
              - string
              - 'null'
              description: Language of the cardholder's browser as defined in IETF BCP47. Maps to EMV 3DS field `browserLanguage`.
            time_zone:
              type:
              - string
              - 'null'
              description: Time zone offset in minutes between UTC and browser local time. Maps to EMV 3DS field `browserTz`.
            user_agent:
              type:
              - string
              - 'null'
              description: Content of the HTTP user-agent header. Maps to EMV 3DS field `browserUserAgent`.
          required: []
        card_expiry_check:
          type: string
          description: Indicates whether the expiration date provided by the cardholder during checkout matches Lithic's record of the card's expiration date.
          enum:
          - MATCH
          - MISMATCH
          - NOT_PRESENT
        card_token:
          type: string
          description: 'Globally unique identifier for the card on which the 3DS authentication has occurred. Permitted values: 36-digit version 4 UUID (including hyphens).'
          format: uuid
        cardholder:
          type: object
          description: Object containing data about the cardholder provided during the transaction.
          properties:
            address_match:
              type:
              - boolean
              - 'null'
              description: Indicates whether the shipping address and billing address provided by the cardholder are the same. This value - and assessment of whether the addresses match - is provided directly in the 3DS request and is not determined by Lithic. Maps to EMV 3DS field `addrMatch`.
            address_on_file_match:
              $ref: '#/components/schemas/address_match_result'
            billing_address:
              type: object
              description: Object containing data on the billing address provided during the transaction.
              properties:
                address1:
                  type:
                  - string
                  - 'null'
                  description: First line of the street address provided by the cardholder.
                address2:
                  type:
                  - string
                  - 'null'
                  description: Second line of the street address provided by the cardholder.
                address3:
                  type:
                  - string
                  - 'null'
                  description: Third line of the street address provided by the cardholder.
                city:
                  type:
                  - string
                  - 'null'
                  description: City of the address provided by the cardholder.
                country:
                  type:
                  - string
                  - 'null'
                  description: Country of the address provided by the cardholder in ISO 3166-1 alpha-3 format (e.g. USA)
                  minLength: 3
                  maxLength: 3
                postal_code:
                  type:
                  - string
                  - 'null'
                  description: Postal code (e.g., ZIP code) of the address provided by the cardholder
            email:
              type:
              - string
              - 'null'
              description: Email address that is either provided by the cardholder or is on file with the merchant in a 3RI request. Maps to EMV 3DS field `email`.
              maxLength: 254
              minLength: 1
            name:
              type:
              - string
              - 'null'
              description: Name of the cardholder. Maps to EMV 3DS field `cardholderName`.
              maxLength: 45
              minLength: 1
            phone_number_home:
              type:
              - string
              - 'null'
              description: Home phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `homePhone.cc` and `homePhone.subscriber`.
              maxLength: 16
              minLength: 1
            phone_number_mobile:
              type:
              - string
              - 'null'
              description: Mobile/cell phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `mobilePhone.cc` and `mobilePhone.subscriber`.
              maxLength: 16
              minLength: 1
            phone_number_work:
              type:
              - string
              - 'null'
              description: Work phone number in E.164 format provided by the cardholder. Maps to EMV 3DS fields `workPhone.cc` and `workPhone.subscriber`.
              maxLength: 16
              minLength: 1
            shipping_address:
              type: object
              description: Object containing data on the shipping address provided during the transaction.
              properties:
                address1:
                  type:
                  - string
                  - 'null'
                  description: First line of the street address provided by the cardholder.
                address2:
                  type:
                  - string
                  - 'null'
                  description: Second line of the street address provided by the cardholder.
                address3:
                  type:
                  - string
                  - 'null'
                  description: Third line of the street address provided by the cardholder.
                city:
                  type:
                  - string
                  - 'null'
                  description: City of the address provided by the cardholder.
                country:
                  type:
                  - string
                  - 'null'
                  description: Country of the address provided by the cardholder in ISO 3166-1 alpha-3 format (e.g. USA)
                  minLength: 3
                  maxLength: 3
                postal_code:
                  type:
                  - string
                  - 'null'
                  description: Postal code (e.g., ZIP code) of the address provided by the cardholder
          required: []
        challenge_metadata:
          type:
          - object
          - 'null'
          description: Metadata about the challenge method and delivery. Only present when a challenge is triggered.
          properties:
            method_type:
              type: string
              enum:
              - SMS_OTP
              - OUT_OF_BAND
              description: The type of challenge method used for authentication.
            phone_number:
              type:
              - string
              - 'null'
              description: The phone number used for delivering the OTP. Relevant only for SMS_OTP method.
            status:
              type: string
              enum:
              - SUCCESS
              - PENDING
              - SMS_DELIVERY_FAILED
              - CARDHOLDER_TIMEOUT
              - CANCELED_VIA_CHALLENGE_UI
              - CANCELED_OOB
              - ATTEMPTS_EXCEEDED
              - ABORTED
              - ERROR
              description: 'Indicates the status of the challenge


                * SUCCESS - Cardholder completed the challenge successfully

                * PENDING - Challenge was issued to the cardholder and was not completed yet

                * SMS_DELIVERY_FAILED - Lithic confirmed undeliverability of the SMS to the provided phone number. Relevant only for SMS_OTP method

                * CARDHOLDER_TIMEOUT - Cardholder failed to complete the challenge within the given challenge TTL

                * CANCELED_VIA_CHALLENGE_UI - Cardholder canceled the challenge by selecting "cancel" on the challenge UI

                * CANCELED_OOB - Cardholder canceled the challenge out of band

                * ATTEMPTS_EXCEEDED - Cardholder failed the challenge by either entering an incorrect OTP more than the allowed number of times or requesting a new OTP more than the allowed number of times

                * ABORTED - Merchant aborted authentication after a challenge was requested

                * ERROR - The challenge failed for a reason different than those documented'
          required:
          - method_type
          - status
        challenge_orchestrated_by:
          type:
          - string
          - 'null'
          description: Entity that orchestrates the challenge. This won't be set for authentications for which a decision has not yet been made (e.g. in-flight customer decisioning request).
          enum:
          - LITHIC
          - CUSTOMER
          - NO_CHALLENGE
          - null
        channel:
          type: string
          description: Channel in which the authentication occurs. Maps to EMV 3DS field `deviceChannel`.
          enum:
          - APP_BASED
          - BROWSER
          - THREE_DS_REQUESTOR_INITIATED
        created:
          type: string
          description: 'Date and time when the authentication was created in Lithic''s system. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd''T''hh:mm:ssZ.'
          format: date-time
        decision_made_by:
          type:
          - string
          - 'null'
          description: Entity that made the authentication decision. This won't be set for authentications for which a decision has not yet been made (e.g. in-flight customer decisioning request).
          enum:
          - LITHIC_RULES
          - LITHIC_DEFAULT
          - CUSTOMER_RULES
          - CUSTOMER_ENDPOINT
          - NETWORK
          - UNKNOWN
          - null
        merchant:
          type: object
          description: Object containing data about the merchant involved in the e-commerce transaction.
          properties:
            country:
              type:
              - string
              - 'null'
              description: 'Country code of the merchant requesting 3DS authentication. Maps to EMV 3DS field `merchantCountryCode`. Permitted values: ISO 3166-1 alpha-3 country code (e.g., USA). May not be present for non-payment authentications.'
              minLength: 3
              maxLength: 3
            id:
              type:
              - string
              - 'null'
              description: Merchant identifier as assigned by the acquirer. Maps to EMV 3DS field `acquirerMerchantId`. May not be present for non-payment authentications.
            mcc:
              type:
              - string
              - 'null'
              description: Merchant category code assigned to the merchant that describes its business activity type. Maps to EMV 3DS field `mcc`. May not be present for non-payment authentications.
              minLength: 4
              maxLength: 4
            name:
              type:
              - string
              - 'null'
              description: Name of the merchant. Maps to EMV 3DS field `merchantName`. May not be present for non-payment authentications.
            risk_indicator:
              type: object
              description: Object containing additional data indicating additional risk factors related to the e-commerce transaction.
              properties:
                delivery_email_address:
                  type:
                  - string
                  - 'null'
                  description: In transactions with electronic delivery, email address to which merchandise is delivered. Maps to EMV 3DS field `deliveryEmailAddress`.
                delivery_time_frame:
                  type:
                  - string
                  - 'null'
                  description: The delivery time frame for the merchandise. Maps to EMV 3DS field `deliveryTimeframe`.
                  enum:
                  - ELECTRONIC_DELIVERY
                  - OVERNIGHT_SHIPPING
                  - SAME_DAY_SHIPPING
                  - TWO_DAY_OR_MORE_SHIPPING
                  - null
                gift_card_amount:
                  type:
                  - integer
                  - 'null'
                  description: In prepaid or gift card purchase transactions, purchase amount total in major units (e.g., a purchase of USD $205.10 would be 205). Maps to EMV 3DS field `giftCardAmount`.
                gift_card_count:
                  type:
                  - integer
                  - 'null'
                  description: In prepaid or gift card purchase transactions, count of individual prepaid or gift cards/codes purchased. Maps to EMV 3DS field `giftCardCount`.
                gift_card_currency:
                  type:
                  - string
                  - 'null'
                  description: 'In prepaid or gift card purchase transactions, currency code of the gift card. Maps to EMV 3DS field `giftCardCurr`. Permitted values: ISO 4217 three-character currency code (e.g., USD).'
                  minLength: 3
                  maxLength: 3
                order_availability:
                  type:
                  - string
                  - 'null'
                  description: Indicates whether the purchase is for merchandise that is available now or at a future date. Maps to EMV 3DS field `preOrderPurchaseInd`.
                  enum:
                  - FUTURE_AVAILABILITY
                  - MERCHANDISE_AVAILABLE
                  - null
                pre_order_available_date:
                  type:
                  - string
                  - 'null'
                  description: 'In pre-order purchase transactions, the expected date that the merchandise will be available. Maps to EMV 3DS field `preOrderDate`. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd''T''hh:mm:ssZ'
                  format: date-time
                reorder_items:
                  type:
                  - string
                  - 'null'
                  description: Indicates whether the cardholder is reordering previously purchased merchandise. Maps to EMV 3DS field `reorderItemsInd`.
                  enum:
                  - FIRST_TIME_ORDERED
                  - REORDERED
                  - null
                shipping_method:
                  type:
                  - string
                  - 'null'
                  description: Shipping method that the cardholder chose for the transaction. If purchase includes one or more item, this indicator is used for the physical goods; if the purchase only includes digital goods, this indicator is used to describe the most expensive item purchased. Maps to EMV 3DS field `shipIndicator`.
                  enum:
                  - DIGITAL_GOODS
                  - LOCKER_DELIVERY
                  - OTHER
                  - PICK_UP_AND_GO_DELIVERY
                  - SHIP_TO_BILLING_ADDRESS
                  - SHIP_TO_NON_BILLING_ADDRESS
                  - SHIP_TO_OTHER_VERIFIED_ADDRESS
                  - SHIP_TO_STORE
                  - TRAVEL_AND_EVENT_TICKETS
                  - null
              required: []
          required:
          - risk_indicator
        message_category:
          type: string
          description: Either PAYMENT_AUTHENTICATION or NON_PAYMENT_AUTHENTICATION. For NON_PAYMENT_AUTHENTICATION, additional_data and transaction fields are not populated.
          enum:
          - NON_PAYMENT_AUTHENTICATION
          - PAYMENT_AUTHENTICATION
        three_ds_requestor_challenge_indicator:
          type: string
          description: 'Indicates whether a challenge is requested for this transaction


            * `NO_PREFERENCE` - No Preference

            * `NO_CHALLENGE_REQUESTED` - No Challenge Requested

            * `CHALLENGE_PREFERENCE` - Challenge requested (3DS Requestor preference)

            * `CHALLENGE_MANDATE` - Challenge requested (Mandate)

            * `NO_CHALLENGE_RISK_ALREADY_ASSESSED` - No Challenge requested (Transactional risk analysis is already performed)

            * `DATA_SHARE_ONLY` - No Challenge requested (Data Share Only)

            * `OTHER` - Other indicators not captured by above. These are rarely used'
          enum:
          - NO_PREFERENCE
          - NO_CHALLENGE_REQUESTED
          - CHALLENGE_PREFERENCE
          - CHALLENGE_MANDATE
          - NO_CHALLENGE_RISK_ALREADY_ASSESSED
          - DATA_SHARE_ONLY
          - OTHER
        three_ri_request_type:
          type:
          - string
          - 'null'
          description: Type of 3DS Requestor Initiated (3RI) request — i.e., a 3DS authentication that takes place at the initiation of the merchant rather than the cardholder. The most common example of this is where a merchant is authenticating before billing for a recurring transaction such as a pay TV subscription or a utility bill. Maps to EMV 3DS field `threeRIInd`.
          enum:
          - ACCOUNT_VERIFICATION
          - ADD_CARD
          - BILLING_AGREEMENT
          - CARD_SECURITY_CODE_STATUS_CHECK
          - DELAYED_SHIPMENT
          - DEVICE_BINDING_STATUS_CHECK
          - INSTALLMENT_TRANSACTION
          - MAIL_ORDER
          - MAINTAIN_CARD_INFO
          - OTHER_PAYMENT
          - RECURRING_TRANSACTION
          - SPLIT_PAYMENT
          - SPLIT_SHIPMENT
          - TELEPHONE_ORDER
          - TOP_UP
          - TRUST_LIST_STATUS_CHECK
          - null
        token:
          type: string
          description: 'Globally unique identifier for the 3DS authentication. Permitted values: 36-digit version 4 UUID (including hyphens).'
          format: uuid
        transaction:
          type:
          - object
          - 'null'
          description: Object containing data about the e-commerce transaction for which the merchant is requesting authentication.
          properties:
            amount:
              type: number
              description: Amount of the purchase in minor units of currency with all punctuation removed. Maps to EMV 3DS field `purchaseAmount`.
            cardholder_amount:
              type:
              - number
              - 'null'
              description: Approximate amount of the purchase in minor units of cardholder currency. Derived from `amount` using a daily conversion rate.
            currency:
              type: string
              description: 'Currency of the purchase. Maps to EMV 3DS field `purchaseCurrency`. Permitted values: ISO 4217 three-character currency code (e.g., USD).'
              minLength: 3
              maxLength: 3
            currency_exponent:
              type: number
              description: Minor units of currency, as specified in ISO 4217 currency exponent. Maps to EMV 3DS field `purchaseExponent`.
            date_time:
              type: string
              description: 'Date and time when the authentication was generated by the merchant/acquirer''s 3DS server. Maps to EMV 3DS field `purchaseDate`. Permitted values: Date string in the ISO 8601 format yyyy-MM-dd''T''hh:mm:ssZ.'
              format: date-time
            type:
              type:
              - string
              - 'null'
              description: Type of the transaction for which a 3DS authentication request is occurring. Maps to EMV 3DS field `transType`.
              enum:
              - ACCOUNT_FUNDING
              - CHECK_ACCEPTANCE
              - GOODS_SERVICE_PURCHASE
              - PREPAID_ACTIVATION_AND_LOAD
              - QUASI_CASH_TRANSACTION
              - null
          required:
          - amount
          - cardholder_amount
          - currency
          - currency_exponent
          - date_time
          - type
      required:
      - account_type
      - authentication_result
      - card_expiry_check
      - card_token
      - cardholder
      - channel
      - created
      - merchant
      - message_category
      - three_ds_requestor_challenge_indicator
      - token
    simulate-authentication-request:
      title: 3DS Simulation Request object
      type: object
      description: Request object for simulating a 3DS authentication
      properties:
        merchant:
          type: object
          description: Merchant information for the simulated transaction
          properties:
            country:
              type: string
              description: Country of the address provided by the cardholder in ISO 3166-1 alpha-3 format (e.g. USA)
              example: USA
            id:
              type: string
              description: Unique identifier to identify the payment card acceptor. Corresponds to `merchant_acceptor_id` in authorization.
              example: OODKZAPJVN4YS7O
              maxLength: 15
              minLength: 1
            mcc:
              type: string
              description: Merchant category code for the transaction to be simulated. A four-digit number listed in ISO 18245. Supported merchant category codes can be found [here](https://docs.lithic.com/docs/transactions#merchant-category-codes-mccs).
              example: '5812'
            name:
              type: string
              description: Merchant descriptor, corresponds to `descriptor` in authorization. If CHALLENGE keyword is included, Lithic will trigger a challenge.
              example: COFFEE SHOP
              maxLength: 25
              minLength: 1
          required:
          - country
          - id
          - mcc
          - name
        pan:
          type: string
          description: Sixteen digit card number.
          example: '4111111289144142'
          maxLength: 16
          minLength: 16
        transaction:
          type: object
          description: Transaction details for the simulation
          properties:
            amount:
              type: integer
              description: Amount (in cents) to authenticate.
              minimum: 0
            currency:
              type: string
              description: 3-character alphabetic ISO 4217 currency code.
              example: GBP
          required:
          - amount
          - currency
        card_expiry_check:
          type: string
          description: When set will use the following values as part of the Simulated Authentication. When not set defaults to MATCH
          enum:
          - MATCH
          - MISMATCH
          - NOT_PRESENT
      required:
      - merchant
      - pan
      - transaction
    address_match_result:
      title: Address Match Result
      description: Lithic's evaluation result comparing the transaction's address data with the cardholder KYC data if it exists. In the event Lithic does not have any Cardholder KYC data, or the transaction does not contain any address data, NOT_PRESENT will be returned
      type: string
      enum:
      - MATCH
      - MATCH_ADDRESS_ONLY
      - MATCH_ZIP_ONLY
      - MISMATCH
      - NOT_PRESENT
    challenge-response:
      title: Challenge Response object
      type: object
      description: Response from Card Program to a 3DS Authentication challenge
      properties:
        token:
          type: string
          description: Globally unique identifier for 3DS Authentication that resulted in PENDING_CHALLENGE authentication result.
          format: uuid
        challenge_response:
          type: string
          description: Whether the Cardholder has approved or declined the issued Challenge
          enum:
          - APPROVE
          - DECLINE_BY_CUSTOMER
      required:
      - token
      - challenge_response
    challenge-response-unprocessable:
      title: Challenge Response Unprocessable
      type: object
      description: Error response when a challenge cannot be completed because it has already been marked complete. Common causes include challenge timeout, too many attempts, or cancellation. Refer to the message parameter for the specific reason
      properties:
        message:
          type: string
          description: Error message explaining why the challenge could not be completed
      required:
      - message
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: '|   |   |

        |---|---|

        | User has not been authenticated | Invalid or missing API key |

        | API key is not active | The API key used is no longer active |

        | Could not find API key | The API key provided is not associated with any user |

        | Please provide API key in Authorization header | The Authorization header is not in the request |

        | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly |

        | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at [lithic.com/contact](https://lithic.com/contact) |

        | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) |

        '
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: A parameter in the query given in the request does not match the valid queries for the endpoint.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: The specified resource was not found.
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: 'Client has exceeded the number of allowed requests in a given time period.


        |   |   |

        |---|---|

        | Rate limited, too many requests per second | User has exceeded their per second rate limit |

        | Rate limited, reached daily limit | User has exceeded their daily rate limit |

        | Rate limited, too many keys tried | One IP has queried too many different API keys |

        '
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: Unprocessable entity.
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey