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
| Attributes | Description |
|---|---|
| acquirer_fee | Fee assessed by the merchant in USD cents. Will be zero if no fee is assessed. In rare cases, amount can be negative to indicate a credited fee. |
| acquirer_reference_number | Unique 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). |
| amount | Amount of the transaction in USD cents, including any acquirer fees. This will initially reflect the authorization amount but will change to the settled amount once any portion of a transaction is settled. |
| authorization_amount | Amount 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_code | Six-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.address | Cardholder address. |
| avs.zipcode | Cardholder ZIP code. |
| card_token | Unique 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- ACQUIRER_EXEMPTION: The acquirer utilized an exemption to bypass Strong Customer Authentication (transStatus = N, or transStatus = I). Liability remains with the acquirer and in this case the acquirer_exemption field is expected to be not NONE. |
| 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: - APP_LOGIN: Out-of-band login verification was attempted by the ACS.- BIOMETRIC: Out-of-band biometric verification was attempted by the ACS.- NONE: No cardholder verification was attempted by the Access Control Server (e.g. frictionless 3-D Secure flow, no 3-D Secure, or stand-in Risk Based Analysis).- OTHER: Other method was used by the ACS to verify the cardholder (e.g. Mastercard Identity Check Express, recurring transactions, etc.)- OTP: One-time password verification was attempted by the ACS. |
| cardholder_authentication. verification_result (deprecated) | This field partially maps to the transStatus field in the EMVCo 3-D Secure specification and Mastercard SPA2 AAV leading indicators. Verification result values: - CANCELLED: Authentication/Account verification could not be performed, transStatus = U.- FAILED: Transaction was not authenticated. transStatus = N, note: the utilization of exemptions could also result in transStatus = N, inspect the acquirer_exemption field for more information.- FRICTIONLESS: Attempts processing performed, the transaction was not authenticated, but a proof of attempted authentication/verification is provided. transStatus = A and the leading AAV indicator was one of {kE, kF, kQ}.- NOT_ATTEMPTED: A 3-D Secure flow was not applied to this transaction. Leading AAV indicator was one of {kN, kX} or no AAV was provided for the transaction.- REJECTED: Authentication/Account Verification rejected; transStatus = R. Issuer is rejecting authentication/verification and requests that authorization not be attempted.- SUCCESS: Authentication verification successful. transStatus = Y and leading AAV indicator for the transaction was one of {kA, kB, kC, kD, kO, kP, kR, kS}.Note that the following transStatus values are not represented by this field: C: Challenge RequiredD: Challenge Required; decoupled authentication confirmedI: Informational onlyS: Challenge using Secure Payment Confirmation (SPC) |
| created | ISO 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.amount | Amount of the transaction event, including any acquirer fees. Debits will appear as positive amounts and credits will appear as negative amounts. |
| event.created | ISO 8601 format (yyyy-MM-dd’T’hh:mm:ssZ) date and time when the transaction was created in Lithic's system. |
| event.detailed_results (array) | Detailed result or outcome of the event. This field is an array, though is currently only be populated with a single detailed result code. Multiple result codes may appear for a single event in the future. The set of enum values for this field may expand over time, and user systems should be prepared to handle new enum values. Possible enum values: - If approved, APPROVED- If declined, see here for full list |
| event.result | Result or outcome of the event. Possible enum values: - If approved, APPROVED- If declined, see here for full list To be deprecated in future version. Refer to event.detailed_results field for more granular result codes. |
| event.token | Unique identifier for the event. |
| event.type | Indicator 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_amount | Analogous to the authorization_amount attribute, but represents the amount in the smallest unit of the transaction's local currency, including any acquirer fees. |
| merchant_amount | Analogous to the amount attribute, but represents the amount in the smallest unit of the transaction's local currency, including any acquirer fees. |
| merchant_currency | ISO 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_id | Unique alphanumeric identifier for the payment card acceptor (merchant). |
| merchant.city | City 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.country | Country 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.descriptor | Short description of the card acceptor. |
| merchant.mcc | Merchant's category code - see here for possible enum values. |
| merchant.state | Geographic state of the card acceptor. |
| network | Card network of the transaction. Possible enum values are INTERLINK, MAESTRO, MASTERCARD, VISA, UNKNOWN. |
| network_risk_score | Network-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.attended | True if a clerk is present at the sale. Otherwise, false. |
| pos.terminal.on_premise | True if the sale was made at the place of business (vs. remotely such as via mobile). |
| pos.terminal.operator | The 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_capable | True if terminal has card retention capability. Otherwise, false. |
| pos.terminal.pin_capability | Indicator for whether the POS is able to accept PINs. Possible enum values are CAPABLE, INOPERATIVE, NOT_CAPABLE, UNSPECIFIED. |
| pos.terminal.type | Point 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_capable | True 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.pan | Method 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_entered | True if a PIN was entered. Otherwise, false. |
| pos.entry_mode.cardholder | Indicator 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.card | Indicator for whether card was present or not. Possible enum values are PRESENT, NOT_PRESENT. |
| result | Outcome of the transaction. Possible enum values: - If approved, APPROVED- If declined, see here for full list |
| settled_amount | Amount in USD cents that has been settled, including any acquirer fees. This may change over time. |
| status | Indicator for where this transaction object currently is in the transaction lifecycle. Possible enum values are PENDING, VOIDED, SETTLED, DECLINED, EXPIRED. |
| token | Unique 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_type | Source 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",
"detailed_results": [
"APPROVED"
],
"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"
}
}