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-financialFinancial
RequestsA 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 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 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 typically 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 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-financialAdvice
Credit Authorization AdviceAn advice message that indicates a credit authorization was approved upstream on your behalf upstream (most typically by the network).Non-financialAdvice
Authorization ReversalAn 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-financialAdvice
ClearingAn advice message that indicates a merchant has captured the transaction, and money has moved.FinancialAdvice
ReturnAn advice message that indicates a refund has been processed on the transaction, and money has moved.FinancialAdvice
Return ReversalAn 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.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

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": [
      "card_token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
      "amount": -7666,
      "authorization_amount": -7666,
      "merchant_amount": -7666,
      "merchant_authorization_amount": -7666,
      "merchant_currency": "USD",
      "acquirer_fee": 0,
      "created": "2020-07-15T19:17:22Z",
      "events": [
          {
              "amount": 7666,
              "created": "2020-07-15T19:17:22Z",
              "result": "APPROVED",
              "type": "RETURN",
              "token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0"
          }
      ],
      "merchant": {
          "acceptor_id": "174030075991",
          "city": "NEW YORK",
          "country": "USA",
          "descriptor": "RESTAURANT ABC",
          "mcc": "5812",
          "state": "NY"
      },
      "result": "APPROVED",
      "settled_amount": -7666,
      "status": "SETTLING",
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
      "authorization_code": "123456"
    }
  ],
  "page": 1,
  "total_entries": 1,
  "total_pages": 1
}
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)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.
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-1000.
page (optional, query parameter)For pagination - specifies the desired page to be included in the response. For example, if there are 3 total entries, and page_size is 2 (i.e., 2 entries per page), then entering the value 2 for page would return the second page and only the third entry. The default is one.
Integer. Permitted values: 1 or greater.

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

{
      "card_token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
      "amount": -7666,
      "authorization_amount": -7666,
      "merchant_amount": -7666,
      "merchant_authorization_amount": -7666,
      "merchant_currency": "USD",
      "acquirer_fee": 0,
      "created": "2020-07-15T19:17:22Z",
      "events": [
          {
              "amount": 7666,
              "created": "2020-07-15T19:17:22Z",
              "result": "APPROVED",
              "type": "RETURN",
              "token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0"
          }
      ],
      "merchant": {
          "acceptor_id": "174030075991",
          "city": "NEW YORK",
          "country": "USA",
          "descriptor": "RESTAURANT ABC",
          "mcc": "5812",
          "state": "NY"
      },
      "result": "APPROVED",
      "settled_amount": -7666,
      "status": "SETTLING",
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
      "authorization_code": "123456"
}
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

BOUNCEDThere was an error settling the transaction against the funding source. Your API account may be disabled
DECLINEDThe transaction was declined
PENDINGAuthorization is pending completion from the merchant
SETTLINGThe merchant has completed the transaction and the funding source is being debited
SETTLEDThe transaction is complete
VOIDEDThe merchant has voided the previously pending authorization

Transaction.result and events[*].result

ACCOUNT_STATE_REVIEWAccount (to which the card used in the transaction belongs) is under review; relevant to Starter customers only
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_PAUSEDCard state was paused at the time of authorization
CARD_CLOSEDCard 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 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_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. 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_FUNDSEnterprise programs: Transaction was declined because the card's available balance was insufficient to cover the authorization amount.
Starter programs: Please ensure the funding source is connected and up to date.
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