Transaction Object
Learn more about how the Lithic platform uses transactions to inform you about activity taking place on your cards.
A transaction
object is created when a payment or payment-related event takes place on a card. 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.
Our Transaction Flow guide contains detailed examples of scenarios where a transaction
object is created or updated.
Transaction Events
To properly interpret the transaction
object and the underlying card activity that it represents, it is first important to understand the various events that can trigger the creation of the object, or that can be subsequently added to the object's events
array to represent a new lifecycle event.
Transaction events can generally be separated along two dimensions: financial vs. non-financial messages, and requests vs. advice.
Non-financial | Financial | |
---|---|---|
Requests | A message that requires a response but does not move money (e.g., authorization). | A message that requires a response and moves money (e.g., financial authorization). |
Advice | An informational message that does not move money (e.g., auth advice). | An informational message that moves money (e.g., clearing). |
Financial messages prompt movement of funds between accounts (e.g., a clearing message that prompts a withdrawal of funds from a card program's bank account), while non-financial messages do not prompt movement of funds (e.g., an authorization request that induces a hold on funds but doesn’t trigger a payment to the merchant until the transaction is settled).
On the other axis, requests are messages that require a response (i.e., approval or decline) to Lithic, while advice messages don’t require a response other than a notification that the advice was received.
Event Type | Description | Financial or Non-financial | Request or Advice |
---|---|---|---|
Authorization | A dual-message authorization request from a merchant has taken place on the card. If approved, a subsequent clearing is typically expected. | Non-financial | Request |
Financial Authorization | A single-message authorization request from a merchant has taken place on the card, and no subsequent clearing is expected. | Financial | Request |
Credit Authorization | A dual-message credit or refund authorization request from a merchant has taken place on the card. If approved, a subsequent clearing is typically expected. | Non-financial | Request |
Financial Credit Authorization | A single-message credit or refund authorization request from a merchant has taken place on the card, and no subsequent clearing is expected. | Financial | Request |
Authorization Advice | An advice message that either indicates that the authorized amount of a previous authorization is being modified, or serves as notice that an authorization was declined upstream on your behalf upstream (most typically by the network). | Non-financial | Advice |
Credit Authorization Advice | An advice message that indicates a credit authorization was approved upstream on your behalf upstream (most typically by the network). | Non-financial | Advice |
Authorization Reversal | An advice message that indicates an authorization was reversed by the merchant. Typical causes of this are because an authorization approval was not received in time, or because the issuer sent back an Address Verification Service (AVS) mismatch result. | Non-financial | Advice |
Clearing | An advice message that indicates a merchant has captured the transaction, and money has moved. | Financial | Advice |
Return | An advice message that indicates a refund has been processed on the transaction, and money has moved. | Financial | Advice |
Return Reversal | An advice message that indicates a refund has been reversed. A typical cause of this is where a merchant needs to reverse an incorrectly issued refund. | Financial | Advice |
Balance Inquiry | A request from a merchant for the card's balance. This is most often seen when a cardholder requests to see their balance via an ATM. | Non-financial | Request |
List Transactions
API Reference: List transactions
GET https://api.lithic.com/v1/transactions
Sample Request
curl https://api.lithic.com/v1/transactions?result=APPROVED&page=1&page_size=50 \
-H "Authorization: YOUR_API_KEY"
Sample Response
{
"data": [
{
"token": "a01db475-f4db-4ddb-b7d3-525954f184e8",
"card_token": "3593c54c-d0fc-4a75-a514-e5e431fba6e5",
"status": "PENDING",
"result": "APPROVED",
"amount": 7500,
"settled_amount": 0,
"authorization_amount": 7500,
"merchant_amount": 7500,
"merchant_authorization_amount": 7500,
"merchant_currency": "USD",
"acquirer_fee": 0,
"authorization_code": null,
"acquirer_reference_number": null,
"merchant": {
"acceptor_id": "174030075991",
"state": "NY",
"city": "NEW YORK",
"country": "USA",
"mcc": "5812",
"descriptor": "COFFEE SHOP"
},
"network": "MASTERCARD",
"events": [
{
"amount": 7500,
"type": "AUTHORIZATION",
"result": "APPROVED",
"created": "2024-02-20T15:22:42Z",
"token": "29918890-a3a0-42c0-bda6-f3d4fb31117b",
"detailed_results": [
"APPROVED"
]
}
],
"created": "2024-02-20T15:22:42Z",
"cardholder_authentication": {
"verification_attempted": "OTHER",
"verification_result": "SUCCESS",
"liability_shift": "3DS_AUTHENTICATED",
"3ds_version": null,
"acquirer_exemption": "MERCHANT_INITIATED_TRANSACTION",
"authentication_result": "SUCCESS",
"three_ds_authentication_token": "fc60d37d-95f7-419c-b628-dd9fbf9d80d0",
"decision_made_by": "NETWORK"
},
"network_risk_score": 5,
"avs": {
"zipcode": "95006",
"address": "123 Evergreen Terrace"
},
"token_info": {
"wallet_type": "APPLE_PAY"
},
"pos": {
"terminal": {
"attended": false,
"operator": "ADMINISTRATIVE",
"on_premise": true,
"card_retention_capable": true,
"pin_capability": "UNSPECIFIED",
"type": "ECR",
"partial_approval_capable": true
},
"entry_mode": {
"pan": "CONTACTLESS",
"pin_entered": true,
"cardholder": "PREAUTHORIZED",
"card": "PREAUTHORIZED"
}
}
}
],
"has_more": false
}
account_token (optional, query parameter) | Globally unique identifier for the account whose associated transactions should be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
card_token (optional, query parameter) | Globally unique identifier for the card whose associated transactions should be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
result (optional, query parameter) | Transaction result type to be returned. String. Permitted values: APPROVED , DECLINED . |
begin (optional, query parameter) | Transaction entries created on or after the specified date will be included. String. Permitted values: Date string in the form YYYY-MM-DD. |
end (optional, query parameter) | Transaction entries created before the specified date will be included (i.e., transaction entries created on the specified date will not be included). String. Permitted values: Date string in the form YYYY-MM-DD. |
starting_after (optional, query parameter) | A cursor representing a transaction entry's token after which a page of results should begin. Used to retrieve the next page of entries after this entry. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
ending_before (optional, query parameter) | A cursor representing a transaction entry's token before which a page of results should end. Used to retrieve the previous page of entries before this entry. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
page_size (optional, query parameter) | For pagination - specifies the number of entries to be included on each page in the response. Default value is 50. Integer. Permitted values: 1-100. |
Get Specific Transactions
API Reference: Get specific transaction
GET https://api.lithic.com/v1/transactions/{transaction_token}
Sample Request
curl https://api.lithic.com/v1/transactions/764fa5a3-2371-40f0-8cbb-9a2e1230d955 \
-H "Authorization: YOUR_API_KEY"
Sample Response
{
"token": "a01db475-f4db-4ddb-b7d3-525954f184e8",
"card_token": "3593c54c-d0fc-4a75-a514-e5e431fba6e5",
"status": "PENDING",
"result": "APPROVED",
"amount": 7500,
"settled_amount": 0,
"authorization_amount": 7500,
"merchant_amount": 7500,
"merchant_authorization_amount": 7500,
"merchant_currency": "USD",
"acquirer_fee": 0,
"authorization_code": null,
"acquirer_reference_number": null,
"merchant": {
"acceptor_id": "174030075991",
"state": "NY",
"city": "NEW YORK",
"country": "USA",
"mcc": "5812",
"descriptor": "COFFEE SHOP"
},
"network": "MASTERCARD",
"events": [
{
"amount": 7500,
"type": "AUTHORIZATION",
"result": "APPROVED",
"created": "2024-02-20T15:22:42Z",
"token": "29918890-a3a0-42c0-bda6-f3d4fb31117b",
"detailed_results": [
"APPROVED"
]
}
],
"created": "2024-02-20T15:22:42Z",
"cardholder_authentication": {
"verification_attempted": "OTHER",
"verification_result": "SUCCESS",
"liability_shift": "3DS_AUTHENTICATED",
"3ds_version": null,
"acquirer_exemption": "MERCHANT_INITIATED_TRANSACTION",
"authentication_result": "SUCCESS",
"three_ds_authentication_token": "fc60d37d-95f7-419c-b628-dd9fbf9d80d0",
"decision_made_by": "NETWORK"
},
"network_risk_score": 5,
"avs": {
"zipcode": "95006",
"address": "123 Evergreen Terrace"
},
"token_info": {
"wallet_type": "APPLE_PAY"
},
"pos": {
"terminal": {
"attended": false,
"operator": "ADMINISTRATIVE",
"on_premise": true,
"card_retention_capable": true,
"pin_capability": "UNSPECIFIED",
"type": "ECR",
"partial_approval_capable": true
},
"entry_mode": {
"pan": "CONTACTLESS",
"pin_entered": true,
"cardholder": "PREAUTHORIZED",
"card": "PREAUTHORIZED"
}
}
}
transaction_token (required, path parameter) | Globally unique identifier for the transaction to be returned. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
Simulate Transactions
Enumerations
Transaction.status
DECLINED | The transaction was declined |
EXPIRED | The authorization validity window (which dictates how long the merchant has to clear or settle the transaction) has passed. Lithic has automatically expired the authorization |
PENDING | Authorization is pending completion from the merchant |
SETTLED | The transaction is complete |
VOIDED | The merchant has voided the previously pending authorization |
Transaction.result and events[*].result
ACCOUNT_STATE_TRANSACTION_FAIL | Contact [email protected] |
APPROVED | Successful transaction |
AUTH_RULE_ALLOWED_COUNTRY | Transaction was declined because the merchant's country is not contained in the set of allowed MCCs configured via Auth Rules |
AUTH_RULE_ALLOWED_MCC | Transaction was declined because the merchant's merchant category code (MCC) is not contained in the set of allowed MCCs configured via Auth Rules |
AUTH_RULE_BLOCKED_COUNTRY | Transaction was declined because the merchant's country is contained in the set of blocked countries configured via Auth Rules |
AUTH_RULE_BLOCKED_MCC | Transaction was declined because the merchant's merchant category code (MCC) is contained in the set of blocked MCCs configured via Auth Rules |
BANK_CONNECTION_ERROR | Please reconnect a funding source |
BANK_NOT_VERIFIED | Please confirm the funding source |
CARD_PAUSED | Transaction was declined either because card program responded to ASA request with a response of CARD_PAUSED or the card’s state was PAUSED at the time of authorization |
CARD_CLOSED | Transaction was declined either because card program responded to ASA request with a response of CARD_CLOSED or the card’s state was CLOSED at the time of authorization |
DECLINED | Transaction was declined for a reason not captured by the other listed reasons |
DO_NOT_HONOR_ADVICE | Transaction was declined due to a decision made by the acquirer or the card network. This is most typically seen when transaction processing takes a long time on the Lithic side, either due to customer's ASA responder taking too long to respond, or the Lithic platform itself taking too long. An advice with this result typically follows a declined authorization or an approved and voided authorization. |
FRAUD_ADVICE | Transaction declined due to risk-related reasons |
IGNORED_TTL_EXPIRY | Authorization could not be processed by the Lithic platform in time |
INACTIVE_ACCOUNT | Contact [email protected] |
INCORRECT_PIN | PIN verification failed. In rare cases, this result can be triggered if the merchant sends through bad PIN data, even if the cardholder was not prompted to enter a PIN during the transaction |
INSUFFICIENT_FUNDS | Transaction was declined because the card's available balance was insufficient to cover the authorization amount. |
INSUFFICIENT_FUNDS_PRELOAD | Result given when client responds to ASA request with INSUFFICIENT_FUNDS . See ASA Response Result |
INVALID_CARD_DETAILS | Incorrect CVV or expiry date |
INVALID_TRANSACTION | Transaction type (for example, inter-account transfer) cannot be processed |
MERCHANT_BLACKLIST | This merchant is disallowed on the platform |
ORIGINAL_NOT_FOUND | Merchant submitted a reversal without a corresponding original |
PREVIOUSLY_COMPLETED | A duplicate message from the network was received on a transaction that has already been completed or cleared |
SINGLE_USE_RECHARGED | Single-use card attempted multiple times |
SWITCH_INOPERATIVE_ADVICE | Network error, re-attempt the transaction |
UNAUTHORIZED_MERCHANT | Merchant locked card attempted at different merchant. |
UNKNOWN | Transaction was declined for an unspecified reason |
UNKNOWN_HOST_TIMEOUT | Network error, re-attempt the transaction |
USER_TRANSACTION_LIMIT | User-set spend limit exceeded |
Events[*].detailed_results
Enum values only relevant for authorization-based events (i.e., may appear associated with event types AUTHORIZATION
, FINANCIAL_AUTHORIZATION
, CREDIT_AUTHORIZATION
, FINANCIAL_CREDIT_AUTHORIZATION
, BALANCE_INQUIRY
):
ACCOUNT_DAILY_SPEND_LIMIT_EXCEEDED | Authorization was declined because authorization amount exceeds the account’s available daily spend limit |
ACCOUNT_INACTIVE | Either card program responded to ASA request with a response of ACCOUNT_INACTIVE or the account object is not in a transactable state (e.g., PAUSED or CLOSED ) |
ACCOUNT_LIFETIME_SPEND_LIMIT_EXCEEDED | Authorizaton was declined because authorization amount exceeds the account’s available lifetime spend limit |
ACCOUNT_MONTHLY_SPEND_LIMIT_EXCEEDED | Authorization was declined because authorization amount exceeds the account’s available monthly spend limit |
ADDRESS_INCORRECT | Authorization was declined because card program responded to ASA request with a response of AVS_INVALID |
AUTH_RULE_ALLOWED_COUNTRY | Authorization was declined because the merchant’s country is not contained in the set of allowed countries configured via Auth Rules |
AUTH_RULE_ALLOWED_MCC | Authorization was declined because the merchant’s merchant category code (MCC) is not contained in the set of allowed MCCs configured via Auth Rules |
AUTH_RULE_BLOCKED_COUNTRY | Authorization was declined because the merchant's country is contained in the set of blocked countries configured via Auth Rules |
AUTH_RULE_BLOCKED_MCC | Authorization was declined because the merchant's merchant category code (MCC) is contained in the set of blocked countries configured via Auth Rules |
CARD_CLOSED | Authorization was declined either because card program responded to ASA request with a response of CARD_CLOSED or the card’s state was CLOSED at the time of authorization |
CARD_EXPIRY_DATE_INCORRECT | Authorization was declined because the expiry date provided was incorrect |
CARD_NOT_ACTIVATED | Authorization was declined because card is in a PENDING_FULFILLMENT or a PENDING_ACTIVATION state. |
CARD_PAUSED | Authorization was declined either because card program responded to ASA request with response of CARD_PAUSED or the card’s state was PAUSED at the time of authorization |
CARD_PIN_INCORRECT | Authorization was declined because the provided PIN was incorrect |
CARD_SECURITY_CODE_INCORRECT | Authorization was declined because the provided security code was incorrect. Excessive occurrences of incorrect security codes on the same card may be an indicator of cardholder confusion or fraud. |
CARD_SPEND_LIMIT_EXCEEDED | Authorization was declined either because the authorization amount exceeds the card’s available spend limit or card program responded to ASA request with response of VELOCITY_EXCEEDED |
CUSTOM_ASA_RESULT | Authorization was declined because the card program responded to ASA request with a decline reason not contained in the predefined set |
CUSTOMER_ASA_TIMEOUT | Authorization was declined because the card program’s ASA responder timed out and did not provide an approve or decline reason within the allotted time |
INVALID_DRIVER | Authorization was declined because transaction had invalid driver number |
INVALID_VEHICLE | Authorization was declined because transaction had invalid vehicle number |
LITHIC_SYSTEM_ERROR | Authorization was declined because of a Lithic system error, and transaction should be re-attempted |
LITHIC_SYSTEM_RATE_LIMIT | Authorization was declined because of a rate limit applied by the Lithic system (most typically when a surge in authorization volume takes place) |
MALFORMED_ASA_RESPONSE | Authorization was declined because the card program’s response to the ASA request did not conform to the specified response structure |
MERCHANT_LOCKED_CARD_ATTEMPTED_ELSEWHERE | Authorization was declined because the merchant-locked card was attempted at a different merchant than the one it is locked to |
MERCHANT_NOT_PERMITTED | Authorization was declined because transactions with the merchant are not permitted on the Lithic platform |
PROGRAM_CARD_SPEND_LIMIT_EXCEEDED | Authorization was declined because the authorization amount exceeds the card’s permitted spend amount (as determined at the program-level) |
PROGRAM_SUSPENDED | Authorization was declined because the program is suspended |
PROGRAM_USAGE_RESTRICTION | Authorization was declined because the transaction violates the program’s terms of use (e.g., transacting at prohibited MCCs) |
SINGLE_USE_CARD_REATTEMPTED | Authorization was declined because the card used is a single use card that has already been used |
UNAUTHORIZED_MERCHANT | Authorization was declined because the card program responded to ASA request with response of UNAUTHORIZED_MERCHANT |
Enum values only relevant for advice-based events (i.e., may appear associated with event types AUTHORIZATION_ADVICE
, CREDIT_AUTHORIZATION_ADVICE
, AUTHORIZATION_REVERSAL
, AUTHORIZATION_EXPIRY
, CLEARING
, RETURN
, RETURN_REVERSAL
):
CARD_RESTRICTED | Network declined the authorization and populated the advice message with a response code indicating “restricted card” |
CONTACT_CARD_ISSUER | Network declined the authorization and populated the advice message with a response code indicating “contact card issuer” |
DO_NOT_HONOR | Network declined the authorization and populated the advice message with a response code indicating “do not honor” |
FORMAT_ERROR | Network declined the authorization and populated the advice message with a response code indicating “format error”. This indicates that the acquirer’s message had a format error, causing an on-behalf decline and subsequent advice message. |
MERCHANT_INVALID | Network declined the authorization and populated the advice message with a response code indicating “invalid merchant” |
OVER_REVERSAL_ATTEMPTED | The merchant attempted to reverse the authorized amount, but the reversal would have caused the transaction amount to go negative |
REVERSAL_UNMATCHED | The merchant attempted to reverse a prior authorization or settlement, but the original event was not found and therefore the reversal is not matched |
TRANSACTION_NOT_PERMITTED_TO_ACQUIRER_OR_TERMINAL | Network declined the authorization and populated the advice message with a response code indicating “transaction not permitted to acquirer/terminal” |
TRANSACTION_NOT_PERMITTED_TO_ISSUER_OR_CARDHOLDER | Network declined the authorization and populated the advice message with a response code indicating “transaction not permitted to issuer/cardholder” |
TRANSACTION_PREVIOUSLY_COMPLETED | The merchant attempted to reverse a prior authorization, but the authorization was already successfully cleared or reversed, and this reversal is considered a duplicate |
Enum values only relevant for both authorization- and advice-based events:
APPROVED | Either the authorization was approved or the network populated the advice message with a response code indicating "success". |
CARD_CRYPTOGRAM_VALIDATION_FAILURE | Either Lithic declined the authorization because the card’s cryptogram could not be validated or the network declined the authorization and populated the advice message with a response code indicating “cryptographic failure” |
CARD_EXPIRED | Either Lithic declined the authorization because the card has an expiry date that has passed or the network declined the authorization and populated the advice message with a response code indicating “expired card” |
CARD_INVALID | Either Lithic declined the authorization because the card details entered are not recognized (e.g., card was just created and has not yet been propagated across Lithic’s system to support an authorization) or the network declined the authorization and populated the advice message with a response code indicating “invalid card number” |
DECLINED | Either Lithic declined the authorization for a reason not captured elsewhere in the set of enums, or the network declined the authorization and populated the advice message with a response code not captured elsewhere in the set of enums |
INSUFFICIENT_FUNDS | Either Lithic declined the authorization because the associated financial account had an insufficient available balance to cover the authorization amount, the card program responded to ASA request with a response of INSUFFICIENT_FUNDS , or the network declined the authorization and populated the advice message with a response code indicating “insufficient funds/over credit limit) |
SECURITY_VIOLATION | Either Lithic declined the authorization because a security violation occurred (e.g., required card security details were not provided) or the network declined the authorization and populated the advice message with a response code indicating “security violation” |
TRANSACTION_INVALID | Either Lithic declined the authorization because the attempted transaction type is not supported or the network declined the authorization and populated the advice message with a response code indicating “invalid transaction” |
Note: Lithic recommends that card programs exercise caution in which of these result codes it passes along to cardholders in order to prevent potential exploitation.
Updated 2 days ago