Lithic Transaction API

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 Transaction API
  version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
  url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Transaction
paths:
  /v1/transactions/{transaction_token}/enhanced_commercial_data:
    get:
      description: Get all L2/L3 enhanced commercial data associated with a transaction. Not available in sandbox.
      summary: List enhanced commercial data
      operationId: listEnhancedTransactionData
      tags:
      - Transaction
      parameters:
      - required: true
        schema:
          title: Transaction Token
          type: string
          format: uuid
        name: transaction_token
        description: The token of the transaction that the enhanced data is associated with.
        in: path
        example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedDataListResponse'
              examples:
                listEnhancedTransactionDataResponse:
                  value:
                    data:
                    - token: fda41769-2a3f-5532-898f-0d2034f2da85
                      transaction_token: 6b79924e-0f01-4bdf-9485-9f6da44b6be2
                      event_token: 49bbd49c-dfe1-56db-86ad-98c7c2bd75e4
                      common:
                        customer_reference_number: null
                        merchant_reference_number: null
                        order_date: null
                        line_items: []
                        tax:
                          merchant_tax_id: '521236050'
                          amount: null
                          exempt: null
                      fleet:
                      - service_type: SELF_SERVICE
                        driver_number: null
                        vehicle_number: '012345'
                        odometer: 12345
                        amount_totals:
                          gross_sale: 104
                          discount: null
                          net_sale: 104
                        fuel:
                          quantity: '0.24300'
                          type: PREMIUM_SUPER
                          unit_of_measure: GALLONS
                          unit_price: 4300
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/transactions/{transaction_token}/expire_authorization:
    post:
      summary: Expire an authorization
      description: Expire authorization
      operationId: expireAuthorization
      tags:
      - Transaction
      parameters:
      - required: true
        schema:
          title: Transaction Token
          type: string
          format: uuid
        name: transaction_token
        description: The token of the transaction to expire.
        in: path
        example: 00000000-0000-0000-0000-000000000000
      responses:
        '202':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/transactions/events/{event_token}/enhanced_commercial_data:
    get:
      description: Get L2/L3 enhanced commercial data associated with a transaction event. Not available in sandbox.
      summary: Get enhanced commercial data
      operationId: getEnhancedTransactionData
      tags:
      - Transaction
      parameters:
      - required: true
        schema:
          title: Event Token
          type: string
          format: uuid
        name: event_token
        description: The token of the transaction event that the enhanced data is associated with.
        in: path
        example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enhanced-data'
              examples:
                getEnhancedTransactionDataResponse:
                  value:
                    token: fda41769-2a3f-5532-898f-0d2034f2da85
                    transaction_token: 6b79924e-0f01-4bdf-9485-9f6da44b6be2
                    event_token: 49bbd49c-dfe1-56db-86ad-98c7c2bd75e4
                    common:
                      customer_reference_number: null
                      merchant_reference_number: null
                      order_date: null
                      line_items: []
                      tax:
                        merchant_tax_id: '521236050'
                        amount: null
                        exempt: null
                    fleet:
                    - service_type: SELF_SERVICE
                      driver_number: null
                      vehicle_number: '012345'
                      odometer: 12345
                      amount_totals:
                        gross_sale: 104
                        discount: null
                        net_sale: 104
                      fuel:
                        quantity: '0.24300'
                        type: PREMIUM_SUPER
                        unit_of_measure: GALLONS
                        unit_price: 4300
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/simulate/authorization_advice:
    post:
      description: 'Simulates an authorization advice from the card network as if it came from a merchant acquirer. An authorization advice changes the pending amount of the transaction.

        '
      operationId: postSimulateAuthorizationAdvice
      requestBody:
        content:
          application/json:
            examples:
              simulateAuthorizationAdvice:
                summary: Simulate an authorization
                value:
                  amount: 3831
                  token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
            schema:
              properties:
                amount:
                  description: Amount (in cents) to authorize. This amount will override the transaction's amount that was originally set by /v1/simulate/authorize.
                  minimum: 0
                  maximum: 2000000000
                  type: integer
                token:
                  description: The transaction token returned from the /v1/simulate/authorize. response.
                  format: uuid
                  type: string
              required:
              - amount
              - token
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: d31645af-da9e-4952-b7dc-3ffb06618b39
                token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                  token:
                    description: A unique token to reference this transaction.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/SimulateAuthorizationFailure'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate authorization advice
      tags:
      - Transaction
  /v1/simulate/authorize:
    post:
      description: 'Simulates an authorization request from the card network as if it came from a merchant acquirer.

        If you are configured for ASA, simulating authorizations requires your ASA client to be set up properly, i.e. be able to respond to the ASA request with a valid JSON. For users that are not configured for ASA, a daily transaction limit of $5000 USD is applied by default. You can update this limit via the [update account](https://docs.lithic.com/reference/patchaccountbytoken) endpoint.

        '
      operationId: postSimulateAuthorize
      requestBody:
        content:
          application/json:
            examples:
              simulateAuthorization:
                summary: Simulate an authorization
                value:
                  amount: 3831
                  descriptor: COFFEE SHOP
                  merchant_acceptor_city: LOS ANGELES
                  merchant_acceptor_state: CA
                  merchant_acceptor_country: USA
                  pan: '4111111289144142'
              simulateBalanceInquiry:
                summary: Simulate a balance inquiry
                value:
                  amount: 0
                  descriptor: NEIGHBORHOOD ATM
                  pan: '4111111289144142'
                  status: BALANCE_INQUIRY
              simulateFinancialCreditAuthorization:
                summary: Simulate a financial credit authorization
                value:
                  amount: 3831
                  descriptor: COFFEE SHOP
                  pan: '4111111289144142'
                  status: FINANCIAL_CREDIT_AUTHORIZATION
            schema:
              properties:
                amount:
                  description: Amount (in cents) to authorize. For credit authorizations and financial credit authorizations, any value entered will be converted into a negative amount in the simulated transaction. For example, entering 100 in this field will result in a -100 amount in the transaction. For balance inquiries, this field must be set to 0.
                  minimum: 0
                  maximum: 2000000000
                  type: integer
                descriptor:
                  description: Merchant descriptor.
                  example: COFFEE SHOP
                  maxLength: 25
                  minLength: 1
                  type: string
                mcc:
                  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'
                  type: string
                merchant_acceptor_id:
                  description: Unique identifier to identify the payment card acceptor.
                  example: OODKZAPJVN4YS7O
                  maxLength: 15
                  minLength: 1
                  type: string
                merchant_acceptor_city:
                  description: Merchant acceptor city
                  example: LOS ANGELES
                  maxLength: 13
                  type: string
                merchant_acceptor_state:
                  description: Merchant acceptor state/province (ISO 3166-2 subdivision code)
                  example: CA
                  maxLength: 3
                  type: string
                merchant_acceptor_country:
                  description: Merchant acceptor country code (ISO 3166-1 alpha-3)
                  example: USA
                  maxLength: 3
                  minLength: 3
                  type: string
                merchant_amount:
                  description: Amount of the transaction to be simulated in currency specified in merchant_currency, including any acquirer fees.
                  type: integer
                merchant_currency:
                  description: '3-character alphabetic ISO 4217 currency code. Note: Simulator only accepts USD, GBP, EUR and defaults to GBP if another ISO 4217 code is provided'
                  example: GBP
                  type: string
                pan:
                  description: Sixteen digit card number.
                  example: '4111111289144142'
                  maxLength: 16
                  minLength: 16
                  type: string
                partial_approval_capable:
                  description: 'Set to true if the terminal is capable of partial approval otherwise false.

                    Partial approval is when part of a transaction is approved and another

                    payment must be used for the remainder.

                    '
                  type: boolean
                pin:
                  description: Simulate entering a PIN. If omitted, PIN check will not be performed.
                  example: '1234'
                  maxLength: 12
                  minLength: 4
                  type: string
                status:
                  default: AUTHORIZATION
                  description: 'Type of event to simulate.

                    * `AUTHORIZATION` is a dual message purchase authorization, meaning a subsequent clearing step is required to settle the transaction.

                    * `BALANCE_INQUIRY` is a $0 authorization requesting the balance held on the card, and is most often observed when a cardholder requests to view a card''s balance at an ATM.

                    * `CREDIT_AUTHORIZATION` is a dual message request from a merchant to authorize a refund, meaning a subsequent clearing step is required to settle the transaction.

                    * `FINANCIAL_AUTHORIZATION` is a single message request from a merchant to debit funds immediately (such as an ATM withdrawal), and no subsequent clearing is required to settle the transaction.

                    * `FINANCIAL_CREDIT_AUTHORIZATION` is a single message request from a merchant to credit funds immediately, and no subsequent clearing is required to settle the transaction.

                    '
                  enum:
                  - AUTHORIZATION
                  - BALANCE_INQUIRY
                  - CREDIT_AUTHORIZATION
                  - FINANCIAL_AUTHORIZATION
                  - FINANCIAL_CREDIT_AUTHORIZATION
                  example: AUTHORIZATION
                  type: string
              required:
              - amount
              - descriptor
              - pan
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: d31645af-da9e-4952-b7dc-3ffb06618b39
                token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                  token:
                    description: A unique token to reference this transaction with later calls to void or clear the authorization.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/SimulateAuthorizationFailure'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate authorization
      tags:
      - Transaction
  /v1/simulate/clearing:
    post:
      description: 'Clears an existing authorization, either debit or credit. After this event, the transaction transitions from `PENDING` to `SETTLED` status.


        If `amount` is not set, the full amount of the transaction will be cleared. Transactions that have already cleared, either partially or fully, cannot be cleared again using this endpoint.

        '
      operationId: postSimulateClearing
      requestBody:
        content:
          application/json:
            examples:
              simulateClear:
                summary: Simulate clearing a transaction
                value:
                  amount: 0
                  token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
            schema:
              properties:
                amount:
                  description: 'Amount (in cents) to clear. Typically this will match the amount in the original authorization, but can be higher or lower. The sign of this amount will automatically match the sign of the original authorization''s amount. For example, entering 100 in this field will result in a -100 amount in the transaction, if the original authorization is a credit authorization.


                    If `amount` is not set, the full amount of the transaction will be cleared. Transactions that have already cleared, either partially or fully, cannot be cleared again using this endpoint.

                    '
                  maximum: 2000000000
                  type: integer
                token:
                  description: The transaction token returned from the /v1/simulate/authorize response.
                  format: uuid
                  type: string
              required:
              - token
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: 3ec51ef1-b68d-4243-be6c-2204229b09cf
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                type: object
          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 clearing
      tags:
      - Transaction
  /v1/simulate/credit_authorization_advice:
    post:
      description: 'Simulates a credit authorization advice from the card network.

        This message indicates that the network approved a credit authorization on your behalf.

        '
      operationId: postSimulateCreditAuthorizationAdvice
      requestBody:
        content:
          application/json:
            examples:
              simulateCreditAuthorizationAdvice:
                summary: Simulate a credit authorization advice
                value:
                  amount: 3831
                  descriptor: COFFEE SHOP
                  merchant_acceptor_id: XRKGDPOWEWQRRWU
                  merchant_acceptor_city: SEATTLE
                  merchant_acceptor_state: WA
                  merchant_acceptor_country: USA
                  pan: '4111111289144142'
            schema:
              properties:
                amount:
                  description: Amount (in cents). Any value entered will be converted into a negative amount in the simulated transaction. For example, entering 100 in this field will appear as a -100 amount in the transaction.
                  minimum: 0
                  maximum: 2000000000
                  type: integer
                descriptor:
                  description: Merchant descriptor.
                  example: COFFEE SHOP
                  maxLength: 25
                  minLength: 1
                  type: string
                mcc:
                  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'
                  type: string
                merchant_acceptor_id:
                  description: Unique identifier to identify the payment card acceptor.
                  example: XRKGDPOWEWQRRWU
                  maxLength: 15
                  minLength: 1
                  type: string
                merchant_acceptor_city:
                  description: Merchant acceptor city
                  example: SEATTLE
                  maxLength: 13
                  type: string
                merchant_acceptor_state:
                  description: Merchant acceptor state/province (ISO 3166-2 subdivision code)
                  example: WA
                  maxLength: 3
                  type: string
                merchant_acceptor_country:
                  description: Merchant acceptor country code (ISO 3166-1 alpha-3)
                  example: USA
                  maxLength: 3
                  minLength: 3
                  type: string
                pan:
                  description: Sixteen digit card number.
                  example: '4111111289144142'
                  maxLength: 16
                  minLength: 16
                  type: string
              required:
              - amount
              - descriptor
              - pan
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: d31645af-da9e-4952-b7dc-3ffb06618b39
                token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                  token:
                    description: A unique token to reference this transaction.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/SimulateAuthorizationFailure'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate credit authorization advice
      tags:
      - Transaction
  /v1/simulate/return:
    post:
      description: 'Returns, or refunds, an amount back to a card. Returns simulated via this endpoint clear immediately, without prior authorization, and result in a `SETTLED` transaction status.

        '
      operationId: postSimulateReturn
      requestBody:
        content:
          application/json:
            examples:
              simulateReturn:
                summary: Simulate a return
                value:
                  amount: 3831
                  descriptor: COFFEE SHOP
                  pan: '4111111289144142'
            schema:
              properties:
                amount:
                  description: Amount (in cents) to authorize.
                  minimum: 0
                  maximum: 2000000000
                  type: integer
                descriptor:
                  description: Merchant descriptor.
                  example: COFFEE SHOP
                  maxLength: 25
                  minLength: 1
                  type: string
                pan:
                  description: Sixteen digit card number.
                  example: '4111111289144142'
                  maxLength: 16
                  minLength: 16
                  type: string
              required:
              - amount
              - descriptor
              - pan
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: d31645af-da9e-4952-b7dc-3ffb06618b39
                token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                  token:
                    description: A unique token to reference this transaction.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate return
      tags:
      - Transaction
  /v1/simulate/return_reversal:
    post:
      description: 'Reverses a return, i.e. a credit transaction with a `SETTLED` status. Returns can be financial credit authorizations, or credit authorizations that have cleared.

        '
      operationId: postSimulateReturnReversal
      requestBody:
        content:
          application/json:
            examples:
              simulateReturnReversal:
                summary: Simulate a return reversal
                value:
                  token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
            schema:
              properties:
                token:
                  description: The transaction token returned from the /v1/simulate/authorize response.
                  format: uuid
                  type: string
              required:
              - token
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: d31645af-da9e-4952-b7dc-3ffb06618b39
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate return reversal
      tags:
      - Transaction
  /v1/simulate/void:
    post:
      description: 'Voids a pending authorization. If `amount` is not set, the full amount will be voided. Can be used on partially voided transactions but not partially cleared transactions. _Simulating an authorization expiry on credit authorizations or credit authorization advice is not currently supported but will be added soon._

        '
      operationId: postSimulateVoid
      requestBody:
        content:
          application/json:
            examples:
              simulateAuthorizationExpiry:
                summary: Simulate expiring a transaction
                value:
                  amount: 100
                  token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
                  type: AUTHORIZATION_EXPIRY
              simulateAuthorizationReversal:
                summary: Simulate reversing a transaction
                value:
                  amount: 100
                  token: fabd829d-7f7b-4432-a8f2-07ea4889aaac
                  type: AUTHORIZATION_REVERSAL
            schema:
              properties:
                amount:
                  description: Amount (in cents) to void. Typically this will match the amount in the original authorization, but can be less. Applies to authorization reversals only. An authorization expiry will always apply to the full pending amount.
                  minimum: 0
                  maximum: 2000000000
                  type: integer
                token:
                  description: The transaction token returned from the /v1/simulate/authorize response.
                  format: uuid
                  type: string
                type:
                  default: AUTHORIZATION_REVERSAL
                  description: 'Type of event to simulate. Defaults to `AUTHORIZATION_REVERSAL`.


                    * `AUTHORIZATION_EXPIRY` indicates authorization has expired and been reversed by Lithic.

                    * `AUTHORIZATION_REVERSAL` indicates authorization was reversed by the merchant.

                    '
                  enum:
                  - AUTHORIZATION_EXPIRY
                  - AUTHORIZATION_REVERSAL
                  example: AUTHORIZATION_EXPIRY
                  type: string
              required:
              - token
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                debugging_request_id: 3ec51ef1-b68d-4243-be6c-2204229b09cf
              schema:
                properties:
                  debugging_request_id:
                    description: Debugging request ID to share with Lithic Support team.
                    format: uuid
                    type: string
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Simulate void
      tags:
      - Transaction
  /v1/transactions:
    get:
      description: 'List card transactions. All amounts are in the smallest unit of their respective currency (e.g., cents for USD) and inclusive of any acquirer fees.

        '
      operationId: getTransactions
      parameters:
      - description: 'Filters for transactions associated with a specific account.

          '
        in: query
        name: account_token
        schema:
          format: uuid
          type: string
      - description: Filters for transactions associated with a specific card.
        in: query
        name: card_token
        schema:
          format: uuid
          type: string
      - description: Filters for transactions using transaction result field. Can filter by `APPROVED`, and `DECLINED`.
        in: query
        name: result
        schema:
          enum:
          - APPROVED
          - DECLINED
          type: string
      - in: query
        description: Filters for transactions using transaction status field.
        name: status
        required: false
        schema:
          $ref: '#/components/schemas/card_transaction_status_filter'
      - $ref: '#/components/parameters/beginTime'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/endingBefore'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startingAfter'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_transactions_response'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List card transactions
      tags:
      - Transaction
  /v1/transactions/{transaction_token}:
    get:
      description: 'Get a specific card transaction. All amounts are in the smallest unit of their respective currency (e.g., cents for USD).

        '
      operationId: getTransactionByToken
      parameters:
      - $ref: '#/components/parameters/transactionToken'
      responses:
        '200':
      

# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lithic/refs/heads/main/openapi/lithic-transaction-api-openapi.yml