v66

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

Event Types

card_transaction.updated

Occurs when a card transaction happens.

postWebhookcard_transaction.updated

Payload

event_type'card_transaction.updated' required

The type of event that occurred.

acquirer_feeinteger nullable required

Fee assessed by the merchant and paid for by the cardholder in the smallest unit of the currency. Will be zero if no fee is assessed. Rebates may be transmitted as a negative value to indicate credited fees.

acquirer_reference_numberstring nullable required

Unique identifier assigned to a transaction by the acquirer that can be used in dispute and chargeback filing. This field has been deprecated in favor of the acquirer_reference_number that resides in the event-level network_info.

account_tokenstring uuid required

The token for the account associated with this transaction.

amountinteger required

When the transaction is pending, this represents the authorization amount of the transaction in the anticipated settlement currency. Once the transaction has settled, this field represents the settled amount in the settlement currency.

authorization_amountinteger nullable required

The authorization amount of the transaction in the anticipated settlement currency.

authorization_codestring nullable required

A fixed-width 6-digit numeric identifier that can be used to identify a transaction with networks.

card_tokenstring uuid required

Token for the card used in this transaction.

createdstring date-time required

Date and time when the transaction first occurred. UTC time zone.

financial_account_tokenstring uuid nullable required

merchant_amountinteger nullable required

Analogous to the 'amount', but in the merchant currency.

merchant_authorization_amountinteger nullable required

Analogous to the 'authorization_amount', but in the merchant currency.

merchant_currencystring required

3-character alphabetic ISO 4217 code for the local currency of the transaction.

Card network of the authorization. Value is UNKNOWN when Lithic cannot determine the network code from the upstream provider.

network_risk_scoreinteger nullable required

Network-provided score assessing risk level associated with a given authorization. Scores are on a range of 0-999, with 0 representing the lowest risk and 999 representing the highest risk. For Visa transactions, where the raw score has a range of 0-99, Lithic will normalize the score by multiplying the raw score by 10x.

settled_amountinteger required

The settled amount of the transaction in the settlement currency.

status'DECLINED' | 'EXPIRED' | 'PENDING' | 'SETTLED' | 'VOIDED' required

Status of the transaction.

tokenstring uuid required

Globally unique identifier.

tagsTags required

Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes.

updatedstring date-time required

Date and time when the transaction last updated. UTC time zone.

Example payload

{
  "account_token": "db3942f0-0627-4887-a190-1ea83b46d091",
  "acquirer_fee": 0,
  "acquirer_reference_number": null,
  "amount": 1800,
  "amounts": {
    "cardholder": {
      "amount": 0,
      "conversion_rate": "1.000000",
      "currency": "USD"
    },
    "hold": {
      "amount": -1800,
      "currency": "USD"
    },
    "merchant": {
      "amount": 0,
      "currency": "USD"
    },
    "settlement": {
      "amount": 0,
      "currency": "USD"
    }
  },
  "authorization_amount": 1800,
  "authorization_code": "071471",
  "avs": {
    "zipcode": "95006",
    "address": "123 Evergreen Terrace"
  },
  "card_token": "aac502f9-aecc-458a-954e-4bcf6edb6123",
  "cardholder_authentication": {
    "liability_shift": "3DS_AUTHENTICATED",
    "authentication_result": "SUCCESS",
    "authentication_method": "FRICTIONLESS",
    "three_ds_authentication_token": "fc60d37d-95f7-419c-b628-dd9fbf9d80d0",
    "decision_made_by": "NETWORK"
  },
  "created": "2023-08-03T18:42:30Z",
  "events": [
    {
      "amount": 1800,
      "amounts": {
        "cardholder": {
          "amount": 1800,
          "conversion_rate": "1.000000",
          "currency": "USD"
        },
        "merchant": {
          "amount": 1800,
          "currency": "USD"
        },
        "settlement": null
      },
      "created": "2023-08-03T18:42:30Z",
      "detailed_results": [
        "APPROVED"
      ],
      "effective_polarity": "DEBIT",
      "network_info": {
        "acquirer": {
          "acquirer_reference_number": null,
          "retrieval_reference_number": "064386558597"
        },
        "amex": null,
        "mastercard": {
          "banknet_reference_number": "U1HSCJ",
          "switch_serial_number": null,
          "original_banknet_reference_number": null,
          "original_switch_serial_number": null
        },
        "visa": null
      },
      "result": "APPROVED",
      "rule_results": [],
      "token": "bbbf1e86-322d-11ee-9779-00505685a123",
      "type": "AUTHORIZATION"
    }
  ],
  "financial_account_token": "a3b113e8-01fe-42d3-b900-b9adf3f15496",
  "merchant": {
    "acceptor_id": "452322000053360",
    "acquiring_institution_id": "333301802529120",
    "city": "gosq.com",
    "country": "USA",
    "descriptor": "SQ *SOMA EATS",
    "mcc": "5812",
    "state": "CA",
    "postal_code": "94107",
    "street_address": null,
    "phone_number": null
  },
  "service_location": null,
  "merchant_amount": 1800,
  "merchant_authorization_amount": 1800,
  "merchant_currency": "USD",
  "network": "MASTERCARD",
  "network_risk_score": 5,
  "pos": {
    "entry_mode": {
      "card": "NOT_PRESENT",
      "cardholder": "NOT_PRESENT",
      "pan": "ECOMMERCE",
      "pin_entered": false
    },
    "terminal": {
      "attended": false,
      "card_retention_capable": false,
      "on_premise": false,
      "operator": "UNKNOWN",
      "partial_approval_capable": false,
      "pin_capability": "NOT_CAPABLE",
      "type": "UNKNOWN"
    }
  },
  "result": "APPROVED",
  "settled_amount": 0,
  "status": "PENDING",
  "tags": {
    "risk-level": "high"
  },
  "token": "c30c2182-1e69-4e0d-b40f-eec0d2a19123",
  "token_info": {
    "wallet_type": "APPLE_PAY"
  },
  "updated": "2023-08-03T18:42:30Z"
}

Response

Return a 200 status to indicate that the data was received successfully