Transaction

A transaction object is created when a payment or payment-related event takes place on a card issued via the Lithic platform. Examples of events triggering the creation of a transaction object include a purchase authorization such as when a card is used to spend at a coffee shop, or a credit authorization such as when a merchant requests to issue a refund to the card.

The object is also updated whenever new events take place that modify the transaction. An example of this is when an outstanding purchase authorization is cleared by the merchant.

See Card Transactions Guide for more details.

The Transaction object

AttributesDescription
acquirer_feeFee 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_numberUnique identifier assigned to a transaction by the acquirer that can be used in dispute and chargeback filing. This is only populated once a transaction has been cleared, and is not available for all transactions. Known cases where ARN will not be present are: automated fuel dispenser (AFD) transactions, single message transactions, and authorizations that are never cleared. A single transaction can have multiple ARNs if the merchant sends multiple clearings. These are most commonly seen in the case of e-commerce (e.g., where a merchant clears purchases each time goods within a larger order are shipped) and travel (e.g., where an airline sends a unique clearing record per passenger per flight segment).
amountAmount of the transaction in USD cents, including any acquirer fees. This may change over time, and represents the settled amount once any portion of the transaction is settled.
authorization_amountAmount authorized for the transaction in USD cents, including any acquirer fees. This attribute differs from amount when, for example, only part of a transaction has settled. At that point, authorization_amount represents the total authorized amount that may settle, while amount reflects the portion already settled.
authorization_codeSix-digit alphanumeric identifier that can be used to identify a transaction with networks. This code will not exist for all transactions, and will be set with a null value in cases where it does not.
avs (object)Object containing cardholder address information collected by the merchant that can be used by the issuer for authorization purposes. This data may not be available for all transactions. Where it is not, this object will be set to null.
avs.addressCardholder address.
avs.zipcodeCardholder ZIP code.
card_tokenUnique identifier for the card on which the transaction has occurred.
cardholder_authentication (object)Object containing data about whether authentication of the cardholder was performed prior to the authorization being submitted by the merchant. Cardholder authentication could happen via 3-D Secure or if the transaction takes place with a tokenized payment. If the cardholder is authenticated or the merchant attempts authentication and the issuer declines to verify, liability shift may apply. If it does, the merchant no longer has liability for the transaction and it cannot be charged back for fraud.
cardholder_authentication.
3ds_version (deprecated)
3DS protocol version. Note that this attribute may appear as three_ds_version in some of Lithic's client libraries. Can be:
- 1: 3DS V1 was used.
- 2: 3DS V2 (EMV) was used.
- null: No 3DS was used
cardholder_authentication.
acquirer_exemption
Reason why a low-risk transaction did not use Strong Customer Authentication (SCA). Will always be NONE. Reserved for future use.
cardholder_authentication.
authentication_result
Outcome of the 3DS authentication process. Possible enum values:
- SUCCESS: 3DS authentication was successful and the transaction is considered authenticated
- DECLINE: 3DS authentication was attempted but was unsuccessful — i.e., the issuer declined to authenticate the cardholder; note that Lithic populates this value on a best-effort basis based on common data across the 3DS authentication and ASA data elements
- ATTEMPTS: 3DS authentication was attempted but full authentication did not occur. A proof of attempted authenticated is provided by the merchant.
- NONE: 3DS authentication was not performed on the transaction
cardholder_authentication.
decision_made_by
Indicator for which party made the 3DS authentication decision (see 3DS Decisioning for more details). Possible enum values:
- NETWORK: A network stand-in service decided on the outcome; for token authentications (as indicated in the liability_shift attribute), this is the default value
- LITHIC_DEFAULT: A default decision was made by Lithic, without running a rules-based authentication; this value will be set on card programs that do not participate in one of our two 3DS product tiers
- LITHIC_RULES: A rules-based authentication was conducted by Lithic and Lithic decided on the outcome
- CUSTOMER_ENDPOINT: Lithic customer decided on the outcome based on a real-time request sent to a configured endpoint
- UNKNOWN: Data on which party decided is unavailable
cardholder_authentication.
liability_shift
Indicator for whether liability shift to the issuer applies to the transaction. Possible enum values:
- NONE: Liability has not shifted to the issuer (i.e. the merchant is liable)
- 3DS_AUTHENTICATED: Fully authenticated (possibly recurring) transaction. Liability shift applies
- TOKEN_AUTHENTICATED: Tokenized Payment with validated cryptography, possibly recurring, liability shift applies
cardholder_authentication.
three_ds_authentication_token
Unique identifier you can use to match a given 3DS authentication (available via the three_ds_authentication.created event webhook) and the transaction. Note that in cases where liability shift does not occur, this token is matched to the transaction on a best-effort basis.
cardholder_authentication.
verification_attempted (deprecated)
Indicator for whether a 3DS challenge flow was used, and if so, what the verification method was. Possible enum values:
- NONE: Cardholder verification was not attempted. Authentication was performed via a frictionless flow, not attempted, or via standin risk-based authentication (RBA) .
- OTHER: An undefined method, such as a previously challenged recurring transaction, was used to verify the cardholder.
cardholder_authentication.
verification_result (deprecated)
Indicator for whether a transaction is considered 3DS authenticated. Possible enum values:
- SUCCESS: Authentication Verification Successful.
- FRICTIONLESS: Attempts Processing Performed; Not Authenticated/Verified, but merchant attempted authentication/verification is provided .
- NOT_ATTEMPTED: A 3DS attempt was not made for this transaction.
createdISO 8601 format (yyyy-MM-dd’T’hh:mm:ssZ) date and time when the transaction was created in Lithic's system.
events (array of objects)Array of event objects that modify this transaction. A single transaction may include multiple events that affect the transaction state and lifecycle.
event.amountAmount of the transaction event, including any acquirer fees. Debits will appear as positive amounts and credits will appear as negative amounts.
event.createdISO 8601 format (yyyy-MM-dd’T’hh:mm:ssZ) date and time when the transaction was created in Lithic's system.
event.resultOutcome of the event. Possible enum values:
- If approved, APPROVED
- If declined, see here for full list
event.tokenUnique identifier for the event.
event.typeIndicator for the event type that is modifying the the transaction object. Possible enum values:
- AUTHORIZATION: A dual-message authorization request from merchant where a subsequent clearing is expected.
- FINANCIAL_AUTHORIZATION: A single-message authorization request from merchant to debit funds without a subsequent clearing.
- CREDIT_AUTHORIZATION: A dual-message credit or refund authorization request from merchant where a subsequent clearing is expected.
- FINANCIAL_CREDIT_AUTHORIZATION: A single-message credit or refund authorization request from merchant without a subsequent clearing.
- AUTHORIZATION_ADVICE: An advice message updating the authorized amount of a previous authorization; it does not clear any funds - meaning a subsequent clearing is expected.
- CREDIT_AUTHORIZATION_ADVICE: An advice message indicating that a credit authorization was approve on your behalf by the network.
- AUTHORIZATION_REVERSAL: An advice message indicating that the authorization was reversed by the merchant.
- AUTHORIZATION_EXPIRY: An advice message indicating that the authorization has expired (i.e., the merchant has not cleared the transaction by the expected time) and reversed by Lithic.
- CLEARING: An adviCe message indicating that the merchant has completed the transaction.
- RETURN: An advice message indicating that a refund has been processed on the transaction.
- RETURN_REVERSAL: An advice message indicating that a refund has been reversed (e.g., in a case where the merchant needs to reverse an incorrect refund).
- BALANCE_INQUIRY: A request from merchant for the card's balance (most typically seen with ATMs).
merchant_authorization_amountAnalogous to the authorization_amount attribute, but represents the amount in the smallest unit of the transaction's local currency, including any acquirer fees.
merchant_amountAnalogous to the amount attribute, but represents the amount in the smallest unit of the transaction's local currency, including any acquirer fees.
merchant_currencyISO 4217 alpha-3 currency code for the local currency of the transaction.
merchant (object)Object containing data about the merchant with which the card was used to transact. As additional events are added to the transaction object (e.g., a clearing event), this object's attributes may be updated to reflect the most recent merchant data provided by the network. In rare cases, network messages may not include this detail, and all attributes contained in this object may be blank.
merchant.acceptor_idUnique alphanumeric identifier for the payment card acceptor (merchant).
merchant.cityCity of the card acceptor. In many cases, particularly in card-not-present transactions, merchants may send through a phone number or URL in this attribute.
merchant.countryCountry or entity of the card acceptor. Possible enum values:
- ISO 3166-1 alpha-3 country codes - see here for full list
- QZZ for Kosovo
- ANT for Netherlands Antilles
merchant.descriptorShort description of the card acceptor.
merchant.mccMerchant's category code - see here for possible enum values.
merchant.stateGeographic state of the card acceptor.
networkCard network of the transaction. Possible enum values are INTERLINK, MAESTRO, MASTERCARD, VISA, UNKNOWN.
network_risk_scoreNetwork-provided score assessing risk level associated with a given transaction's authorization event. 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.

A score will only be available for transactions containing an authorization event that had a risk score attached to it, and may not be available for all transactions. Where it is not, this field will be set to null.
pos (object)Object containing data about the point of sale conditions associated with a transaction such as terminal information (attended or not, capable of partial approvals or not, etc.) and how the card information was provided (present or not, PAN entry method, etc.).
pos.terminal (object)Object containing data about the terminal used during the transaction.
pos.terminal.attendedTrue if a clerk is present at the sale. Otherwise, false.
pos.terminal.on_premiseTrue if the sale was made at the place of business (vs. remotely such as via mobile).
pos.terminal.operatorThe person that is intended to operate the terminal (i.e., execute the transaction). Possible enum values are CARDHOLDER, CARD_ACCEPTOR, ADMINISTRATIVE.
pos.terminal.card_retention_capableTrue if terminal has card retention capability. Otherwise, false.
pos.terminal.pin_capabilityIndicator for whether the POS is able to accept PINs. Possible enum values are CAPABLE, INOPERATIVE, NOT_CAPABLE, UNSPECIFIED.
pos.terminal.typePoint of sale terminal type. Possible enum values are ATM, AUTHORIZATION, COUPON_MACHINE, DIAL_TERMINAL, ECOMMERCE, ECR (electronic cash register), FUEL_MACHINE, HOME_TERMINAL, MICR, OFF_PREMISE, PAYMENT, PDA, PHONE, POINT, POS_TERMINAL, SELF_SERVICE, TELEVISION, TELLER, TRAVELERS_CHECK_MACHINE, VENDING, VOICE.
pos.terminal.partial_approval_capableTrue if the terminal is capable of partial approval. Partial approval is when part of a transaction is approved and another payment must be used for the remainder. Example scenario: A $40 transaction is attempted on a prepaid card with a $25 balance. If partial approval is enabled, $25 can be authorized, at which point the POS will prompt the user for an additional payment of $15. See Partial Approval for more information on how to partially approve authorizations.
pos.entry_mode (object)Object containing data about how the card information was entered.
pos.entry_mode.panMethod of entry for the PAN (primary account number). Possible enum values:
- AUTO_ENTRY: PAN auto-entry via server (issuer, acquirer, or third party vendor system)
- BAR_CODE: PAN auto-entry via bar code or QR code reader
- CONTACTLESS: Contactless via chip
- CREDENTIAL_ON_FILE: Credential on file
- ECOMMERCE: PAN or token entry via electronic commerce
- ERROR_KEYED: Chip card or chip-capable terminal was unable to process the transaction using the data on the chip or magnetic stripe, the PAN was entered manually, or the acquirer is not certified to process chip fallback to magnetic stripe
- ERROR_MAGNETIC_STRIPE: Chip card or chip-capable terminal was unable to process the transaction using the data on the chip, therefore the PAN was entered via magnetic stripe
- ICC: PAN auto-entry via chip; ICC stands for Integrated Circuit Card
- KEY_ENTERED: Manually keyed
- MAGNETIC_STRIPE: Magnetic stripe entry
- MANUAL: Manual entry
- OCR: PAN auto-entry via OCR
- SECURE_CARDLESS: Secure cardless entry
- UNSPECIFIED: Unspecified method of entry
- UNKNOWN: Unknown or unmapped method of entry
pos.entry_mode.pin_enteredTrue if a PIN was entered. Otherwise, false.
pos.entry_mode.cardholderIndicator for whether the cardholder was present or not. Possible enum values:
- DEFERRED_BILLING: Deferred billing payment
- ELECTRONIC_ORDER: Cardholder not present; electronic order (e.g., via home PC, Internet, mobile phone, PDA)
- INSTALLMENT: Installment payment
- MAIL_ORDER: Cardholder not present; mail or fascimile order
- NOT_PRESENT: Cardholder not present; unspecified
- PRESENT: Cardholder present
- REOCCURRING: Standing order or recurring transaction
- TELEPHONE_ORDER: Cardholder not present; phone or Automated Response Unit (ARU) order
pos.entry_mode.cardIndicator for whether card was present or not. Possible enum values are PRESENT, NOT_PRESENT.
resultOutcome of the transaction. Possible enum values:
- If approved, APPROVED
- If declined, see here for full list
settled_amountAmount in USD cents that has been settled, including any acquirer fees. This may change over time.
statusIndicator for where this transaction object currently is in the transaction lifecycle. Possible enum values are PENDING, VOIDED, SETTLED, DECLINED, EXPIRED.
tokenUnique identifier for the transaction.
token_info (object)Object containing data relating to the tokenized payment method used to execute the transaction, if applicable.
token_info.wallet_typeSource of the token. Possible token sources include digital wallets or merchant tokenization. Possible enum values are APPLE_PAY, GOOGLE_PAY, SAMSUNG_PAY, MERCHANT, OTHER, MASTERPASS (not currently used, reserved for future use).

Example Transaction object

{
  "acquirer_fee": 0,
  "acquirer_reference_number": "12345678987654321234567",
  "amount": 1500,
  "authorization_amount": 1500,
  "authorization_code": "123456",
  "avs": {
    "address": "1 MAIN ST",
    "zipcode": "10001"
  },
  "card_token": "19c22c47-7a75-43ee-9891-595419830f7e",
  "cardholder_authentication": {
    "3ds_version": "2",
    "acquirer_exemption": "NONE",
    "authentication_result": "SUCCESS",
    "decision_made_by": "LITHIC_RULES",
    "liability_shift": "3DS_AUTHENTICATED",
    "verification_attempted": "NONE",
    "verification_result": "FRICTIONLESS",
    "three_ds_authentication_token": "a6e372d0-b40a-43eb-b0d1-4e1aebef5875"
  },
  "created": "2023-09-26T21:14:28.637Z",
  "events": [
    {
      "amount": 1500,
      "created": "2023-09-26T21:14:28.637Z",
      "result": "APPROVED",
      "token": "0c2adae9-f535-4505-8c35-421dad9bd0b6",
      "type": "AUTHORIZATION"
    }
  ],
  "merchant": {
    "acceptor_id": "333301802529120",
    "city": "NEW YORK",
    "country": "USA",
    "descriptor": "COFFEE SHOP",
    "mcc": "5812",
    "state": "NY"
  },
  "merchant_amount": 1500,
  "merchant_authorization_amount": 1500,
  "merchant_currency": "USD",
  "network": "MASTERCARD",
  "network_risk_score": 200,
  "result": "APPROVED",
  "settled_amount": 1500,
  "status": "SETTLED",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "token_info": {
    "wallet_type": "APPLE_PAY"
  }
}