--- title: "List card transactions" method: GET path: "/v1/transactions" tags: ["Transaction"] --- # List card transactions `GET /v1/transactions` 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. ## Query parameters - `account_token` string, uuid - `card_token` string, uuid - `result` 'APPROVED' | 'DECLINED' - `status` 'PENDING' | 'VOIDED' | 'SETTLED' | 'DECLINED' | 'EXPIRED' - `begin` string, date-time - `end` string, date-time - `ending_before` string - `page_size` integer - `starting_after` string ## Response `200` OK - ListTransactionsResponse - `data` CardTransaction[] - `acquirer_fee` integer, 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_number` string, 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_token` string, uuid, required — The token for the account associated with this transaction. - `amount` integer, 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. - `amounts` TransactionAmounts, required - `cardholder` object, required - `amount` integer, required — The estimated settled amount of the transaction in the cardholder billing currency. - `conversion_rate` string, required — The exchange rate used to convert the merchant amount to the cardholder billing amount. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `hold` object, required - `amount` integer, required — The pending amount of the transaction in the anticipated settlement currency. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `merchant` object, required - `amount` integer, required — The settled amount of the transaction in the merchant currency. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `settlement` object, required - `amount` integer, required — The settled amount of the transaction in the settlement currency. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `authorization_amount` integer, nullable, required — The authorization amount of the transaction in the anticipated settlement currency. - `authorization_code` string, nullable, required — A fixed-width 6-digit numeric identifier that can be used to identify a transaction with networks. - `avs` Avs, required - `address` string, required — Cardholder address - `zipcode` string, required — Cardholder ZIP code - `card_token` string, uuid, required — Token for the card used in this transaction. - `cardholder_authentication` CardholderAuthentication, required - `authentication_result` 'ATTEMPTS' | 'DECLINE' | 'NONE' | 'SUCCESS', required — Indicates the outcome of the 3DS authentication process. - `authentication_method` 'FRICTIONLESS' | 'CHALLENGE' | 'NONE', required — Indicates the method used to authenticate the cardholder. - `decision_made_by` 'CUSTOMER_RULES' | 'CUSTOMER_ENDPOINT' | 'LITHIC_DEFAULT' | 'LITHIC_RULES' | 'NETWORK' | 'UNKNOWN', required — Indicates which party made the 3DS authentication decision. - `liability_shift` '3DS_AUTHENTICATED' | 'TOKEN_AUTHENTICATED' | 'NONE', required — Indicates whether chargeback liability shift applies to the transaction. Possible enum values: * `3DS_AUTHENTICATED`: The transaction was fully authenticated through a 3-D Secure flow, chargeback liability shift applies. * `NONE`: Chargeback liability shift has not shifted to the issuer, i.e. the merchant is liable. * `TOKEN_AUTHENTICATED`: The transaction was a tokenized payment with validated cryptography, possibly recurring. Chargeback liability shift to the issuer applies. - `three_ds_authentication_token` string, uuid, nullable, required — 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. - `created` string, date-time, required — Date and time when the transaction first occurred. UTC time zone. - `events` TransactionEvent[] - `account_type` 'CHECKING' | 'SAVINGS' - `amount` integer, required — Amount of the event in the settlement currency. - `amounts` TransactionEventAmounts, required - `cardholder` object, required - `amount` integer, required — Amount of the event in the cardholder billing currency. - `conversion_rate` string, required — Exchange rate used to convert the merchant amount to the cardholder billing amount. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `merchant` object, required - `amount` integer, required — Amount of the event in the merchant currency. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `settlement` object, nullable, required - `amount` integer, required — Amount of the event, if it is financial, in the settlement currency. Non-financial events do not contain this amount because they do not move funds. - `conversion_rate` string, required — Exchange rate used to convert the merchant amount to the settlement amount. - `currency` string, required — 3-character alphabetic ISO 4217 currency - `created` string, date-time, required — RFC 3339 date and time this event entered the system. UTC time zone. - `network_info` NetworkInfo, nullable, required — Information provided by the card network in each event. This includes common identifiers shared between you, Lithic, the card network and in some cases the acquirer. These identifiers often link together events within the same transaction lifecycle and can be used to locate a particular transaction, such as during processing of disputes. Not all fields are available in all events, and the presence of these fields is dependent on the card network and the event type. If the field is populated by the network, we will pass it through as is unless otherwise specified. Please consult the official network documentation for more details about these fields and how to use them. - `acquirer` object, nullable, required - `acquirer_reference_number` string, nullable, required — Identifier assigned by the acquirer, applicable to dual-message transactions only. The acquirer reference number (ARN) is only populated once a transaction has been cleared, and it is not available in all transactions (such as automated fuel dispenser transactions). A single transaction can contain multiple ARNs if the merchant sends multiple clearings. - `retrieval_reference_number` string, nullable, required — Identifier assigned by the acquirer. - `amex` object, nullable, required - `transaction_id` string, nullable, required — Identifier assigned by American Express to link original messages to subsequent messages. Guaranteed by American Express to be unique for each original authorization and financial authorization. - `original_transaction_id` string, nullable, required — Identifier assigned by American Express. Matches the `transaction_id` of a prior related event. May be populated in incremental authorizations (authorization requests that augment a previously authorized amount), authorization advices, financial authorizations, and clearings. - `mastercard` object, nullable, required - `banknet_reference_number` string, nullable, required — Identifier assigned by Mastercard. Guaranteed by Mastercard to be unique for any transaction within a specific financial network on any processing day. - `switch_serial_number` string, nullable, required — Identifier assigned by Mastercard, applicable to single-message transactions only. - `original_banknet_reference_number` string, nullable, required — Identifier assigned by Mastercard. Matches the `banknet_reference_number` of a prior related event. May be populated in authorization reversals, incremental authorizations (authorization requests that augment a previously authorized amount), automated fuel dispenser authorization advices and clearings, and financial authorizations. If the original banknet reference number contains all zeroes, then no actual reference number could be found by the network or acquirer. If Mastercard converts a transaction from dual-message to single-message, such as for certain ATM transactions, it will populate the original banknet reference number in the resulting financial authorization with the banknet reference number of the initial authorization, which Lithic does not receive. - `original_switch_serial_number` string, nullable, required — Identifier assigned by Mastercard. Matches the `switch_serial_number` of a prior related event. May be populated in returns and return reversals. Applicable to single-message transactions only. - `visa` object, nullable, required - `transaction_id` string, nullable, required — Identifier assigned by Visa to link original messages to subsequent messages. Guaranteed by Visa to be unique for each original authorization and financial authorization. - `original_transaction_id` string, nullable, required — Identifier assigned by Visa. Matches the `transaction_id` of a prior related event. May be populated in incremental authorizations (authorization requests that augment a previously authorized amount), authorization advices, financial authorizations, and clearings. - `network_specific_data` NetworkSpecificData - `mastercard` MastercardNetworkSpecificData, required - `transaction_type_identifier` string, nullable, required — Indicates the type of additional transaction purpose. - `ecommerce_security_level_indicator` string, nullable, required — Indicates the electronic commerce security level and UCAF collection. - `on_behalf_service_result` object[], nullable, required — The On-behalf Service performed on the transaction and the results. Contains all applicable, on-behalf service results that were performed on a given transaction. - `service` string, required — Indicates the service performed on the transaction. - `result_1` string, required — Indicates the results of the service processing. - `result_2` string, required — Identifies the results of the service processing. - `visa` VisaNetworkSpecificData, required - `business_application_identifier` string, nullable, required — Identifies the purpose or category of a transaction, used to classify and process transactions according to Visa’s rules. - `detailed_results` DetailedResult[], required - `rule_results` RuleResult[], required - `auth_rule_token` string, uuid, nullable, required — The Auth Rule Token associated with the rule from which the decline originated. If this is set to null, then the decline was not associated with a customer-configured Auth Rule. This may happen in cases where a transaction is declined due to a Lithic-configured security or compliance rule, for example. - `result` 'ACCOUNT_DAILY_SPEND_LIMIT_EXCEEDED' | 'ACCOUNT_DELINQUENT' | 'ACCOUNT_INACTIVE' | 'ACCOUNT_LIFETIME_SPEND_LIMIT_EXCEEDED' | 'ACCOUNT_MONTHLY_SPEND_LIMIT_EXCEEDED' | 'ACCOUNT_PAUSED' | 'ACCOUNT_UNDER_REVIEW' | 'ADDRESS_INCORRECT' | 'APPROVED' | 'AUTH_RULE_ALLOWED_COUNTRY' | 'AUTH_RULE_ALLOWED_MCC' | 'AUTH_RULE_BLOCKED_COUNTRY' | 'AUTH_RULE_BLOCKED_MCC' | 'AUTH_RULE' | 'CARD_CLOSED' | 'CARD_CRYPTOGRAM_VALIDATION_FAILURE' | 'CARD_EXPIRED' | 'CARD_EXPIRY_DATE_INCORRECT' | 'CARD_INVALID' | 'CARD_NOT_ACTIVATED' | 'CARD_PAUSED' | 'CARD_PIN_INCORRECT' | 'CARD_RESTRICTED' | 'CARD_SECURITY_CODE_INCORRECT' | 'CARD_SPEND_LIMIT_EXCEEDED' | 'CONTACT_CARD_ISSUER' | 'CUSTOMER_ASA_TIMEOUT' | 'CUSTOM_ASA_RESULT' | 'DECLINED' | 'DO_NOT_HONOR' | 'DRIVER_NUMBER_INVALID' | 'FORMAT_ERROR' | 'INSUFFICIENT_FUNDING_SOURCE_BALANCE' | 'INSUFFICIENT_FUNDS' | 'LITHIC_SYSTEM_ERROR' | 'LITHIC_SYSTEM_RATE_LIMIT' | 'MALFORMED_ASA_RESPONSE' | 'MERCHANT_INVALID' | 'MERCHANT_LOCKED_CARD_ATTEMPTED_ELSEWHERE' | 'MERCHANT_NOT_PERMITTED' | 'OVER_REVERSAL_ATTEMPTED' | 'PIN_BLOCKED' | 'PROGRAM_CARD_SPEND_LIMIT_EXCEEDED' | 'PROGRAM_SUSPENDED' | 'PROGRAM_USAGE_RESTRICTION' | 'REVERSAL_UNMATCHED' | 'SECURITY_VIOLATION' | 'SINGLE_USE_CARD_REATTEMPTED' | 'SUSPECTED_FRAUD' | 'TRANSACTION_INVALID' | 'TRANSACTION_NOT_PERMITTED_TO_ACQUIRER_OR_TERMINAL' | 'TRANSACTION_NOT_PERMITTED_TO_ISSUER_OR_CARDHOLDER' | 'TRANSACTION_PREVIOUSLY_COMPLETED' | 'UNAUTHORIZED_MERCHANT' | 'VEHICLE_NUMBER_INVALID' | 'CARDHOLDER_CHALLENGED' | 'CARDHOLDER_CHALLENGE_FAILED', required - `name` string, nullable, required — The name for the rule, if any was configured. - `explanation` string, nullable, required — A human-readable explanation outlining the motivation for the rule's decline. - `effective_polarity` 'CREDIT' | 'DEBIT', required — Indicates whether the transaction event is a credit or debit to the account. - `result` 'ACCOUNT_PAUSED' | 'ACCOUNT_STATE_TRANSACTION_FAIL' | 'APPROVED' | 'BANK_CONNECTION_ERROR' | 'BANK_NOT_VERIFIED' | 'CARD_CLOSED' | 'CARD_PAUSED' | 'DECLINED' | 'FRAUD_ADVICE' | 'IGNORED_TTL_EXPIRY' | 'SUSPECTED_FRAUD' | 'INACTIVE_ACCOUNT' | 'INCORRECT_PIN' | 'INVALID_CARD_DETAILS' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_FUNDS_PRELOAD' | 'INVALID_TRANSACTION' | 'MERCHANT_BLACKLIST' | 'ORIGINAL_NOT_FOUND' | 'PREVIOUSLY_COMPLETED' | 'SINGLE_USE_RECHARGED' | 'SWITCH_INOPERATIVE_ADVICE' | 'UNAUTHORIZED_MERCHANT' | 'UNKNOWN_HOST_TIMEOUT' | 'USER_TRANSACTION_LIMIT', required - `token` string, uuid, required — Transaction event identifier. - `type` 'AUTHORIZATION' | 'AUTHORIZATION_ADVICE' | 'AUTHORIZATION_EXPIRY' | 'AUTHORIZATION_REVERSAL' | 'BALANCE_INQUIRY' | 'CLEARING' | 'CORRECTION_CREDIT' | 'CORRECTION_DEBIT' | 'CREDIT_AUTHORIZATION' | 'CREDIT_AUTHORIZATION_ADVICE' | 'FINANCIAL_AUTHORIZATION' | 'FINANCIAL_CREDIT_AUTHORIZATION' | 'RETURN' | 'RETURN_REVERSAL', required — Type of transaction event - `financial_account_token` string, uuid, nullable, required - `merchant` TransactionMerchant, required — Merchant information including full location details. - `acceptor_id` string, required — Unique alphanumeric identifier for the payment card acceptor (merchant). - `acquiring_institution_id` string, required — Unique numeric identifier of the acquiring institution. - `city` string, required — City of card acceptor. Note that in many cases, particularly in card-not-present transactions, merchants may send through a phone number or URL in this field. - `country` string, required — Country or entity of card acceptor. Possible values are: (1) all ISO 3166-1 alpha-3 country codes, (2) QZZ for Kosovo, and (3) ANT for Netherlands Antilles. - `descriptor` string, required — Short description of card acceptor. - `mcc` string, required — Merchant category code (MCC). A four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides. - `state` string, required — Geographic state of card acceptor. - `postal_code` string, nullable, required — Postal code of card acceptor. - `street_address` string, nullable, required — Street address of card acceptor. - `phone_number` string, nullable, required — Phone number of card acceptor. - `service_location` ServiceLocation, required — Where the cardholder received the service, when different from the card acceptor location. This is populated from network data elements such as Mastercard DE-122 SE1 SF9-14 and Visa F34 DS02. - `street_address` string, nullable, required — Street address of service location. - `city` string, nullable, required — City of service location. - `state` string, nullable, required — State/province code of service location, ISO 3166-2. - `country` string, nullable, required — Country code of service location, ISO 3166-1 alpha-3. - `postal_code` string, nullable, required — Postal code of service location. - `merchant_amount` integer, nullable, required — Analogous to the 'amount', but in the merchant currency. - `merchant_authorization_amount` integer, nullable, required — Analogous to the 'authorization_amount', but in the merchant currency. - `merchant_currency` string, required — 3-character alphabetic ISO 4217 code for the local currency of the transaction. - `network` 'AMEX' | 'INTERLINK' | 'MAESTRO' | 'MASTERCARD' | 'UNKNOWN' | 'VISA', nullable, required — Card network of the authorization. Value is `UNKNOWN` when Lithic cannot determine the network code from the upstream provider. - `network_risk_score` integer, 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. - `result` 'ACCOUNT_PAUSED' | 'ACCOUNT_STATE_TRANSACTION_FAIL' | 'APPROVED' | 'BANK_CONNECTION_ERROR' | 'BANK_NOT_VERIFIED' | 'CARD_CLOSED' | 'CARD_PAUSED' | 'DECLINED' | 'FRAUD_ADVICE' | 'IGNORED_TTL_EXPIRY' | 'SUSPECTED_FRAUD' | 'INACTIVE_ACCOUNT' | 'INCORRECT_PIN' | 'INVALID_CARD_DETAILS' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_FUNDS_PRELOAD' | 'INVALID_TRANSACTION' | 'MERCHANT_BLACKLIST' | 'ORIGINAL_NOT_FOUND' | 'PREVIOUSLY_COMPLETED' | 'SINGLE_USE_RECHARGED' | 'SWITCH_INOPERATIVE_ADVICE' | 'UNAUTHORIZED_MERCHANT' | 'UNKNOWN_HOST_TIMEOUT' | 'USER_TRANSACTION_LIMIT', required - `pos` Pos, required - `entry_mode` PosEntryMode, required - `card` 'NOT_PRESENT' | 'PREAUTHORIZED' | 'PRESENT' | 'UNKNOWN', required — Card presence indicator - `cardholder` 'DEFERRED_BILLING' | 'ELECTRONIC_ORDER' | 'INSTALLMENT' | 'MAIL_ORDER' | 'NOT_PRESENT' | 'PREAUTHORIZED' | 'PRESENT' | 'REOCCURRING' | 'TELEPHONE_ORDER' | 'UNKNOWN', required — Cardholder presence indicator - `pan` 'AUTO_ENTRY' | 'BAR_CODE' | 'CONTACTLESS' | 'CREDENTIAL_ON_FILE' | 'ECOMMERCE' | 'ERROR_KEYED' | 'ERROR_MAGNETIC_STRIPE' | 'ICC' | 'KEY_ENTERED' | 'MAGNETIC_STRIPE' | 'MANUAL' | 'OCR' | 'SECURE_CARDLESS' | 'UNKNOWN' | 'UNSPECIFIED', required — Method of entry for the PAN - `pin_entered` boolean, required — Indicates whether the cardholder entered the PIN. True if the PIN was entered. - `terminal` PosTerminal, required - `attended` boolean, required — True if a clerk is present at the sale. - `card_retention_capable` boolean, required — True if the terminal is capable of retaining the card. - `on_premise` boolean, required — True if the sale was made at the place of business (vs. mobile). - `operator` 'ADMINISTRATIVE' | 'CARDHOLDER' | 'CARD_ACCEPTOR' | 'UNKNOWN', required — The person that is designated to swipe the card - `partial_approval_capable` boolean, required — 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. - `pin_capability` 'CAPABLE' | 'INOPERATIVE' | 'NOT_CAPABLE' | 'UNSPECIFIED', required — Status of whether the POS is able to accept PINs - `acceptor_terminal_id` string, nullable — Uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS Systems - `type` 'ADMINISTRATIVE' | 'ATM' | 'AUTHORIZATION' | 'COUPON_MACHINE' | 'DIAL_TERMINAL' | 'ECOMMERCE' | 'ECR' | 'FUEL_MACHINE' | 'HOME_TERMINAL' | 'MICR' | 'OFF_PREMISE' | 'PAYMENT' | 'PDA' | 'PHONE' | 'POINT' | 'POS_TERMINAL' | 'PUBLIC_UTILITY' | 'SELF_SERVICE' | 'TELEVISION' | 'TELLER' | 'TRAVELERS_CHECK_MACHINE' | 'VENDING' | 'VOICE' | 'UNKNOWN', required — POS Type - `settled_amount` integer, required — The settled amount of the transaction in the settlement currency. - `status` 'DECLINED' | 'EXPIRED' | 'PENDING' | 'SETTLED' | 'VOIDED', required — Status of the transaction. - `token` string, uuid, required — Globally unique identifier. - `token_info` TokenInfo, required - `wallet_type` 'APPLE_PAY' | 'GOOGLE_PAY' | 'MASTERPASS' | 'MERCHANT' | 'OTHER' | 'SAMSUNG_PAY', required — The wallet_type field will indicate the source of the token. Possible token sources include digital wallets (Apple, Google, or Samsung Pay), merchant tokenization, and “other” sources like in-flight commerce. Masterpass is not currently supported and is included for future use. - `tags` Tags, required — Key-value pairs for tagging resources. Tags allow you to associate arbitrary metadata with a resource for your own purposes. - `updated` string, date-time, required — Date and time when the transaction last updated. UTC time zone. - `has_more` boolean — Indicates whether there are more transactions to be retrieved. ## Other responses - `400` — A parameter in the query given in the request does not match the valid queries for the endpoint. - `401` — | | | |---|---| | 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) | - `404` — The specified resource was not found. - `429` — 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 | --- [API](https://skmtc.net/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.net/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/53ab5d4e2adb/schema)