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 are an authorization to make a purchase at a store and a credit authorization requested by a merchant to issue a refund.

The transaction object updates whenever new events take place that modify the transaction. An example of this is when a merchant clears an outstanding purchase authorization.

Our Transaction Flow guide contains detailed examples of scenarios in which 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 important to understand the various events that can either trigger the creation of an object or append to an existing object's events array to signal a new lifecycle event.

Transaction events can generally be separated along two dimensions: financial vs. non-financial messages, and requests vs. advice.

Non-financialFinancial
RequestA 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).
AdviceAn 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 settles).

On the other axis, requests are messages that require a response (i.e., approval or decline) from Lithic, while advice messages only require an acknowledgment of receipt from Lithic.

Event TypeDescriptionFinancial or Non-financialRequest or Advice
AuthorizationA dual-message authorization request from a merchant has taken place on the card. If approved, a subsequent clearing is typically expected.Non-financialRequest
Financial AuthorizationA single-message authorization request from a merchant has taken place on the card, and no subsequent clearing is expected.FinancialRequest
Credit AuthorizationA dual-message credit or refund authorization request from a merchant has taken place on the card. If approved, a subsequent clearing is normally expected.Non-financialRequest
Financial Credit AuthorizationA single-message credit or refund authorization request from a merchant has taken place on the card, and no subsequent clearing is expected.FinancialRequest
Authorization AdviceAn advice message indicating either that the authorized amount of a previous authorization has been modified or that an authorization was declined upstream on your behalf (most typically by the network).Non-financialAdvice
Credit Authorization AdviceAn advice message indicating that a credit authorization was approved upstream on your behalf (most typically by the network).Non-financialAdvice
Authorization ReversalAn advice message indicating that an authorization was reversed by the merchant. Typical causes of this are that an authorization approval was not received in time or the issuer sent back an Address Verification Service (AVS) mismatch result.Non-financialAdvice
ClearingAn advice message indicating either that a merchant has captured the transaction and money has moved, or that a financial authorization was declined upstream on your behalf (most typically by the network).FinancialAdvice
ReturnAn advice message indicating that a refund has been processed on the transaction, and money has moved.FinancialAdvice
Return ReversalAn advice message indicating that a refund has been reversed. A primary motive for this is a merchant needing to reverse an incorrectly issued refund.FinancialAdvice
Balance InquiryA 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-financialRequest

Transaction Amounts

The transaction object contains various amount fields indicating how much the transaction has been authorized and settled for, across any currencies involved. These can be found in the amounts object, which specifies the amounts, currencies, and conversion rates utilized during the transaction. All amounts include any acquirer fees and display in the smallest unit of their corresponding currencies.

The pending amount referred to below represents the total amount authorized that is currently pending completion by the merchant/acquirer. This may change over the course of a transaction lifecycle, depending on which events take place. Events impacting the pending amount are:

  • Non-financial requests. When Lithic approves this type of request, the amount the merchant is authorized to transact on then increases in magnitude. Examples: Authorization and Credit Authorization.
  • Non-financial advices. These increase or decrease the amount the merchant is authorized to transact on, without Lithic's approval. Examples: Authorization Advice and Authorization Reversal.
  • Financial events settling an existing non-financial request or advice. Such events reduce the remaining amount that the merchant can transact on. Examples: Clearing (following an Authorization) and Return (following a Credit Authorization).

How should you use the pending amount?

Pending debit transactions and pending credit transactions differ in how Lithic treats them. The pending amount in both cases indicates the current expectation of funds settling in one direction or the other – merchant to cardholder, or vice versa. However, a pending debit transaction also results in a temporary reduction, or hold, of the cardholder's spending power by the pending amount, to ensure the cardholder does not spend beyond what is permitted. If the transaction settles, this reduction becomes permanent to a full or partial extent, depending on how much has settled; otherwise the reduction is eventually reversed. A pending credit transaction, on the other hand, does not increase the cardholder's spending power. This increase only occurs once the transaction settles and the expectation of funds has been realized, to prevent situations where the credit authorization gets reversed and the cardholder has overspent as a result of the anticipated funds never arriving.

Due to this difference, the pending amount of a debit transaction equates to the actual hold placed on the cardholder's spending power. This materializes as a decrease in the available balance to spend (for a debit or prepaid card program) or a decrease in the available credit (for a credit card program). The pending amount is also summed into the total spend controlled by any spend limits. Meanwhile, the pending amount of a credit transaction has no impact, except to signal that the cardholder may receive funds from the merchant. Customers integrating Lithic with their own or a third-party ledger are strongly encouraged to treat the pending amount as described above.

The settled amount referred to below represents the total amount of the transaction that has settled. This may change over the course of a transaction lifecycle. Financial events impact the settled amount, while non-financial events do not.

Note, balance inquiries do not affect any amounts, because these are purely informational requests from the merchant.

A transaction may span multiple currencies during its lifecycle, by authorizing in one currency and settling in another. To capture this, Lithic displays amounts in the following types of currencies:

  • The cardholder billing currency is the currency the card is issued in and the currency the cardholder is typically billed in.
  • The merchant currency, also known as the transaction currency, is the currency used by the merchant/acquirer when submitting the transaction to the network.
  • The settlement currency is the currency that settlement (actual funds movement) takes place in.

How do the amounts in these currencies relate to each other?

  1. In each event, the merchant specifies the desired amount in its default currency; this is called the merchant amount, or transaction amount.
  2. If the cardholder billing currency differs from the merchant currency, the card network converts the merchant amount to the cardholder billing currency to yield the cardholder billing amount. The network pins the exchange rate at the time of the first event in the transaction and reuses it for any subsequent events in this transaction. Applying a fixed exchange rate across all stages of the transaction provides a consistent experience to the cardholder, by ensuring that the pending amount displayed on the cardholder's account matches the final amount in the statement issued to the cardholder.
  3. If the event is financial and the settlement currency differs from the merchant currency, then the card network converts the merchant amount to the settlement currency. The conversion rate used here is not pinned, meaning the network will apply the live exchange rate to any subsequent financial event in this transaction (see our guide to Multiple Completion). The settlement amount output by this conversion represents how much will actually settle between the issuer and the network for this particular event. Due to fluctuating conversion rates and network fees, this will deviate from the cardholder billing amount.

Lithic exposes all of these amounts, as well as the conversion rates used, to give customers transparency into how much their transactions are pending or settling for at each stage. Customers may use the cardholder billing amount to bill cardholders, but should keep in mind that actual funds movement occurs in the settlement amount. Lithic utilizes the settlement amount when updating balances within our ledger.

Let's look at an example illustrating the concepts above. A person with a card issued in Canada makes a 100 AUD purchase at a store in Sydney. Assume this takes place as a dual-message system transaction. The merchant sends an authorization request to the card network with a merchant amount of 100 AUD, and the network pins and uses the current conversion rate of 1 AUD to 0.9159 CAD to calculate a cardholder billing amount of 91.59 CAD. Lithic receives and approves this authorization request. The next day, the merchant submits a clearing of 100 AUD to settle the transaction. The network uses the pinned rate to calculate a cardholder billing amount of 91.59 CAD. Suppose settlement takes place in CAD; then the network uses the live conversion rate of 1 AUD to 0.9160 CAD to calculate a settlement amount of 91.60 CAD. The settlement amount differs from the cardholder billing amount by 0.01 CAD.

Below describes the amount fields in the transaction object, along with the events that can affect them. These are negative for a debit transaction and positive for a credit transaction. A full outline of the amounts object can be found here.

FieldDescriptionImpacting Events
amounts.cardholder.amountThe estimated settled amount of the transaction in the cardholder billing currency.Financial Authorization, Financial Credit Authorization, Clearing, Return, Return Reversal
amounts.hold.amountThe pending amount of the transaction in the anticipated settlement currency.Authorization, Credit Authorization, Authorization Advice, Credit Authorization Advice, Authorization Reversal, Clearing, Return
amounts.merchant.amountThe settled amount of the transaction in the merchant currency.Financial Authorization, Financial Credit Authorization, Clearing, Return, Return Reversal
amounts.settlement.amountThe settled amount of the transaction in the settlement currency.Financial Authorization, Financial Credit Authorization, Clearing, Return, Return Reversal

Deprecated Transaction Amount Fields

The transaction object also contains the following fields that are deprecated and will be removed in the future. Lithic will provide advance notice to customers at such time that this occurs.

The authorization amount referred to below represents the total amount requested by the merchant. This may change over the course of a transaction lifecycle, depending on which events take place. Events impacting the authorization amount are:

  • Requests, both financial and non-financial, as they signal the merchant's intent to transact for a given amount. Examples: Authorization and Financial Credit Authorization.
  • Non-financial advices. These events modify the requested transaction amount. Examples: Authorization Advice and Authorization Reversal.
  • Financial advices reversing an existing financial request or advice. Such events unwind, either partially or entirely, the prior funds movement as well as the merchant's intent to trigger this movement. The latter is done to signal that the merchant should reauthorize for the desired amount if it wants to reattempt the funds movement. Examples: Return (following a Clearing) and Return Reversal (following a Return).

All amounts include any acquirer fees and display in the smallest unit of their corresponding currencies.

FieldDescriptionImpacting Events
amountWhen the transaction is pending, this represents the authorization amount of the transaction in the anticipated settlement currency. This field represents the settled amount in the settlement currency once the transaction has settled.All events, except for Balance Inquiry
authorization_amountThe authorization amount of the transaction in the anticipated settlement currency.Authorization, Financial Authorization, Credit Authorization, Financial Credit Authorization, Authorization Advice, Credit Authorization Advice, Authorization Reversal, Return, Return Reversal
merchant_amountAnalogous to the amount, but in the merchant currency.All events, except for Balance Inquiry
merchant_authorization_amountAnalogous to the authorization_amount, but in the merchant currency.Authorization, Financial Authorization, Credit Authorization, Financial Credit Authorization, Authorization Advice, Credit Authorization Advice, Authorization Reversal, Return, Return Reversal
settled_amountThe settled amount of the transaction in the settlement currency.Financial Authorization, Financial Credit Authorization, Clearing, Return, Return Reversal

Transaction Event Amounts

Each event in the transaction object's events array also contains fields detailing, in multiple currency types, the amount requested by the merchant/acquirer, independent of whether the event is approved or declined. These can be found in the event's amounts object, which lists the amounts, currencies, and conversion rates involved. A full outline of the amounts object can be found here.

FieldDescription
amounts.cardholder.amountAmount of the event in the cardholder billing currency.
amounts.merchant.amountAmount of the event in the merchant currency.
amounts.settlement.amountAmount 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.

Deprecated Transaction Event Amount Fields

The transaction event also contains the following fields that are deprecated and will be removed in the future. Lithic will provide advance notice to customers at such time that this occurs.

FieldDescription
amountAmount of the event in the settlement currency.

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": "d180aafd-10a2-485f-91cc-34214b1860e4",
        "card_token": "2a7f861b-cb0c-4100-9e5c-2bc71cb46c21",
        "account_token": "91f1243b-b195-4f4b-814c-7588a4794ced",
        "status": "SETTLED",
        "result": "APPROVED",
        "amounts": {
            "hold": {
              "amount": 0, 
              "currency": "CAD"
            },
            "merchant": {
              "amount": -800, 
              "currency": "USD"
            },
            "cardholder": {
              "amount": -1000,
              "currency": "CAD",
              "conversion_rate": "1.250000"
            },
            "settlement": {
              "amount": -1001, 
              "currency": "CAD"
            }
        },
        "events": [
            {
                "type": "AUTHORIZATION",
                "result": "APPROVED",
                "created": "2024-10-01T17:47:43Z",
                "token": "f59f83a3-fccc-42fb-a81b-5a4def5c5a54",
                "amounts": {
                    "settlement": null,
                    "cardholder": {
                    	"amount": 1000,
                      "currency": "CAD",
                      "conversion_rate": "1.250000"
                    },
                    "merchant": {
                    	"amount": 800, 
                      "currency": "USD"
                    },
                },
                "amount": 1000,
                "effective_polarity": "DEBIT",
                "detailed_results": ["APPROVED"]
            },
            {
                "type": "CLEARING",
                "result": "APPROVED",
                "created": "2024-10-01T17:47:43Z",
                "token": "79c6e4ef-b248-43e0-b959-ce91a0fd0479",
                "amounts": {
                    "settlement": {
                        "amount": 1001,
                        "currency": "CAD",
                        "conversion_rate": "1.251250"
                    },
                    "cardholder": {
                        "amount": 1000,
                        "currency": "CAD",
                        "conversion_rate": "1.250000"
                    },
                    "merchant": {
                      "amount": 800, 
                      "currency": "USD"
                    },
                },
                "amount": 1001,
                "effective_polarity": "DEBIT",
                "detailed_results": ["APPROVED"]
            }
        ],
        "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",
        "created": "2024-10-01T17:47:43Z",
        "updated": "2024-10-01T17:47:43Z",
        "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"
          }
        }
        "amount": 1001,
        "settled_amount": 1001,
        "authorization_amount": 1000,
        "merchant_amount": 800,
        "merchant_authorization_amount": 800,
        "merchant_currency": "USD"
    	}
   ],
   "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": "d180aafd-10a2-485f-91cc-34214b1860e4",
  "card_token": "2a7f861b-cb0c-4100-9e5c-2bc71cb46c21",
  "account_token": "91f1243b-b195-4f4b-814c-7588a4794ced",
  "status": "SETTLED",
  "result": "APPROVED",
  "amounts": {
    "hold": {
      "amount": 0, 
      "currency": "CAD"
    },
    "merchant": {
      "amount": -800, 
      "currency": "USD"
    },
    "cardholder": {
      "amount": -1000,
      "currency": "CAD",
      "conversion_rate": "1.250000"
    },
    "settlement": {
      "amount": -1001, 
      "currency": "CAD"
    }
  },
  "events": [
    {
      "type": "AUTHORIZATION",
      "result": "APPROVED",
      "created": "2024-10-01T17:47:43Z",
      "token": "f59f83a3-fccc-42fb-a81b-5a4def5c5a54",
      "amounts": {
        "settlement": null,
        "cardholder": {
          "amount": 1000,
          "currency": "CAD",
          "conversion_rate": "1.250000"
        },
        "merchant": {
          "amount": 800, 
          "currency": "USD"
        }
      },
      "amount": 1000,
      "effective_polarity": "DEBIT",
      "detailed_results": ["APPROVED"]
    },
    {
      "type": "CLEARING",
      "result": "APPROVED",
      "created": "2024-10-01T17:47:43Z",
      "token": "79c6e4ef-b248-43e0-b959-ce91a0fd0479",
      "amounts": {
        "settlement": {
          "amount": 1001,
          "currency": "CAD",
          "conversion_rate": "1.251250"
        },
        "cardholder": {
          "amount": 1000,
          "currency": "CAD",
          "conversion_rate": "1.250000"
        },
        "merchant": {
          "amount": 800, 
          "currency": "USD"
        }
      },
      "amount": 1001,
      "effective_polarity": "DEBIT",
      "detailed_results": ["APPROVED"]
    }
  ],
  "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",
  "created": "2024-10-01T17:47:43Z",
  "updated": "2024-10-01T17:47:43Z",
  "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"
    }
  },
  "amount": 1001,
  "settled_amount": 1001,
  "authorization_amount": 1000,
  "merchant_amount": 800,
  "merchant_authorization_amount": 800,
  "merchant_currency": "USD"
}
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

See Simulating Transactions.

Enumerations

Transaction.status

DECLINEDThe transaction was declined
EXPIREDThe authorization validity window (which dictates how long the merchant has to clear or settle the transaction) has passed. Lithic has automatically expired the authorization
PENDINGAuthorization is pending completion from the merchant
SETTLEDThe transaction is complete
VOIDEDThe merchant has voided the previously pending authorization

Transaction.result and events[*].result

ACCOUNT_STATE_TRANSACTION_FAILContact [email protected]
APPROVEDSuccessful transaction
AUTH_RULE_ALLOWED_COUNTRYTransaction was declined because the merchant's country is not contained in the set of allowed MCCs configured via Auth Rules
AUTH_RULE_ALLOWED_MCCTransaction 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_COUNTRYTransaction was declined because the merchant's country is contained in the set of blocked countries configured via Auth Rules
AUTH_RULE_BLOCKED_MCCTransaction was declined because the merchant's merchant category code (MCC) is contained in the set of blocked MCCs configured via Auth Rules
BANK_CONNECTION_ERRORPlease reconnect a funding source
BANK_NOT_VERIFIEDPlease confirm the funding source
CARD_PAUSEDTransaction was declined because either the 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_CLOSEDTransaction was declined because either the card program responded to ASA request with a response of CARD_CLOSED or the card’s state was CLOSED at the time of authorization
DECLINEDTransaction was declined for a reason not captured by the other listed reasons
DO_NOT_HONOR_ADVICETransaction was declined due to a decision made by the acquirer or the card network. This is primarily occurs when transaction processing takes a long time on the Lithic side, due to either the customer's ASA responder or the Lithic platform taking too long to respond. An advice with this result typically follows a declined authorization or an approved and voided authorization. On occasion, it may also follow a financial authorization.
FRAUD_ADVICETransaction declined due to risk-related reasons
IGNORED_TTL_EXPIRYAuthorization could not be processed by the Lithic platform in time
INACTIVE_ACCOUNTContact [email protected]
INCORRECT_PINPIN verification failed. This may occur for several reasons, including a PIN entered incorrectly by the cardholder or a PIN transaction attempted while the PIN is blocked due to consecutive incorrect attempts. 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_FUNDSTransaction was declined because the card's available balance was insufficient to cover the authorization amount.
INSUFFICIENT_FUNDS_PRELOADResult given when client responds to ASA request with INSUFFICIENT_FUNDS. See ASA Response Result
INVALID_CARD_DETAILSIncorrect CVV or expiry date
INVALID_TRANSACTIONTransaction type (for example, inter-account transfer) cannot be processed
MERCHANT_BLACKLISTThis merchant is disallowed on the platform
ORIGINAL_NOT_FOUNDMerchant submitted a reversal without a corresponding original
PREVIOUSLY_COMPLETEDA duplicate message from the network was received on a transaction that has already been completed or cleared
SINGLE_USE_RECHARGEDSingle-use card attempted multiple times
SWITCH_INOPERATIVE_ADVICENetwork error, re-attempt the transaction
UNAUTHORIZED_MERCHANTMerchant locked card attempted at different merchant.
UNKNOWNTransaction was declined for an unspecified reason
UNKNOWN_HOST_TIMEOUTNetwork error, re-attempt the transaction
USER_TRANSACTION_LIMITUser-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_EXCEEDEDAuthorization was declined because authorization amount exceeds the account’s available daily spend limit
ACCOUNT_DELINQUENTTransaction was declined because the account is in delinquency
ACCOUNT_INACTIVEEither the 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_EXCEEDEDAuthorization was declined because authorization amount exceeds the account’s available lifetime spend limit
ACCOUNT_MONTHLY_SPEND_LIMIT_EXCEEDEDAuthorization was declined because authorization amount exceeds the account’s available monthly spend limit
ADDRESS_INCORRECTAuthorization was declined because card program responded to ASA request with a response of AVS_INVALID
AUTH_RULE_ALLOWED_COUNTRYAuthorization was declined because the merchant’s country is not contained in the set of allowed countries configured via Auth Rules
AUTH_RULE_ALLOWED_MCCAuthorization 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_COUNTRYAuthorization was declined because the merchant's country is contained in the set of blocked countries configured via Auth Rules
AUTH_RULE_BLOCKED_MCCAuthorization was declined because the merchant's merchant category code (MCC) is contained in the set of blocked countries configured via Auth Rules
CARD_CLOSEDAuthorization was declined because either the 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_INCORRECTAuthorization was declined because the expiry date provided was incorrect
CARD_NOT_ACTIVATEDAuthorization was declined because card is in a PENDING_FULFILLMENT or a PENDING_ACTIVATION state.
CARD_PAUSEDAuthorization was declined because either the 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_INCORRECTAuthorization was declined because the provided PIN was incorrect
CARD_SECURITY_CODE_INCORRECTAuthorization 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_EXCEEDEDAuthorization was declined because either the authorization amount exceeds the card’s available spend limit or the card program responded to ASA request with response of VELOCITY_EXCEEDED
CUSTOM_ASA_RESULTAuthorization was declined because the card program responded to ASA request with a decline reason not contained in the predefined set
CUSTOMER_ASA_TIMEOUTAuthorization was declined because the card program’s ASA responder timed out and did not provide an approve or decline reason within the allotted time
DRIVER_NUMBER_INVALIDAuthorization was declined because transaction had an invalid driver number
VEHICLE_NUMBER_INVALIDAuthorization was declined because transaction had an invalid vehicle number
LITHIC_SYSTEM_ERRORAuthorization was declined because of a Lithic system error, and transaction should be re-attempted
LITHIC_SYSTEM_RATE_LIMITAuthorization was declined because of a rate limit applied by the Lithic system (most typically when a surge in authorization volume takes place)
MALFORMED_ASA_RESPONSEAuthorization was declined because the card program’s response to the ASA request did not conform to the specified response structure
MERCHANT_LOCKED_CARD_ATTEMPTED_ELSEWHEREAuthorization was declined because the merchant-locked card was attempted at a different merchant than the one it is locked to
MERCHANT_NOT_PERMITTEDAuthorization was declined because transactions with the merchant are not permitted on the Lithic platform
PIN_BLOCKEDAuthorization was declined because the card's PIN_STATUS is currently BLOCKED due to excessive consecutive incorrect PIN attempts. To unblock a card's PIN, see the Managing Cards guide here.
PROGRAM_CARD_SPEND_LIMIT_EXCEEDEDAuthorization was declined because the authorization amount exceeds the card’s permitted spend amount (as determined at the program-level)
PROGRAM_SUSPENDEDAuthorization was declined because the program is suspended
PROGRAM_USAGE_RESTRICTIONAuthorization was declined because the transaction violates the program’s terms of use (e.g., transacting at prohibited MCCs)
SINGLE_USE_CARD_REATTEMPTEDAuthorization was declined because the card used is a single use card that has already been used
UNAUTHORIZED_MERCHANTAuthorization 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_RESTRICTEDNetwork declined the authorization and populated the advice message with a response code indicating “restricted card”
CONTACT_CARD_ISSUERNetwork declined the authorization and populated the advice message with a response code indicating “contact card issuer”
DO_NOT_HONORNetwork declined the authorization and populated the advice message with a response code indicating “do not honor”
FORMAT_ERRORNetwork 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_INVALIDNetwork declined the authorization and populated the advice message with a response code indicating “invalid merchant”
OVER_REVERSAL_ATTEMPTEDThe merchant attempted to reverse the authorized amount, but the reversal would have caused the transaction amount to go negative
REVERSAL_UNMATCHEDThe 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_TERMINALNetwork 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_CARDHOLDERNetwork declined the authorization and populated the advice message with a response code indicating “transaction not permitted to issuer/cardholder”
TRANSACTION_PREVIOUSLY_COMPLETEDThe 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:

APPROVEDEither the authorization was approved or the network populated the advice message with a response code indicating "success".
CARD_CRYPTOGRAM_VALIDATION_FAILUREEither 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_EXPIREDEither 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_INVALIDEither 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”
DECLINEDEither 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_FUNDSEither 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_VIOLATIONEither 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_INVALIDEither 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.