Transactions

Learn more about transactions.

Transaction Schema

{
  "amount": Integer,
  "card": Card,
  "created": String,
  "events": [
      Event
  ],
  "funding": [
      {
          "amount": Integer,
          "token": String,
          "type": String
      }
  ],
  "merchant": Merchant,
  "result": String,
  "settled_amount": Integer,
  "status": String,
  "token": String
}
amountAuthorization amount (in cents) of the transaction. This may change over time.
cardSee Card schema definition.
createdDate and time when the transaction first occurred.
events (Issuing) A list of all events that have modified this transaction.
fundingA list of objects that describe how this transaction was funded, with the amount represented in cents. A reference to the funding account for the card that made this transaction may appear here and the token will match the token for the funding account in the card field. If any promotional credit was used in paying for this transaction, its type will be PROMO.
merchantSee Merchant Schema definition below.
resultAPPROVED or decline reason. See below for full enumeration.
settled_amountAmount (in cents) of the transaction that has been settled. This may change over time.
statusPENDING, VOIDED, SETTLING, SETTLED, BOUNCED, DECLINED.
tokenGlobally unique identifier.

Event Schema (Issuing)

{
  "amount": Integer,
  "created": String,
  "result": String,
  "token": String,
  "type": String
}

A single card transaction may include multiple events that affect the transaction state and lifecycle.

amountAmount of the transaction event.
createdDate and time this event entered the system.
resultAPPROVED or decline reason. See below for full enumeration.
tokenGlobally unique identifier
typeAUTHORIZATION, AUTHORIZATION_ADVICE, CLEARING, VOID, RETURN

Merchant Schema

{
  "acceptor_id": String,
  "city": String,
  "country": String,
  "descriptor": String,
  "mcc": String,
  "state": String
}
acceptor_idUnique identifier to identify the payment card acceptor
cityCity of card acceptor
countryCountry of card acceptor
descriptorShort description of card acceptor
mccMerchant category code
stateGeographic state of card acceptor

List Transactions

API reference: List transactions

GET https://api.lithic.com/v1/transaction/:approval_status

Sample Request

curl https://api.lithic.com/v1/transaction/approvals?card_token=764fa5a3-2371-40f0-8cbb-9a2e1230d955 \
  -H "Authorization: api-key YOUR_API_KEY"

Sample Response

{
  "data": [
    {
      "amount": -7666,
      "card": {
          "created": "2020-07-15T17:48:48Z",
          "cvv": "574",
          "exp_month": "07",
          "exp_year": "2026",
          "funding": {
              "account_name": "Sandbox",
              "created": "2020-07-08 17:57:36",
              "last_four": "5263",
              "nickname": "",
              "state": "ENABLED",
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING"
          },
          "hostname": "",
          "last_four": "6749",
          "memo": "card 2",
          "pan": "4111111171826749",
          "spend_limit": 0,
          "spend_limit_duration": "TRANSACTION",
          "state": "OPEN",
          "token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
          "type": "UNLOCKED"
      },
      "created": "2020-07-15T19:17:22Z",
      "events": [
          {
              "amount": 7666,
              "created": "2020-07-15T19:17:22Z",
              "result": "APPROVED",
              "token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0",
              "type": "RETURN"
          }
      ],
      "funding": [
          {
              "amount": -7666,
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING"
          }
      ],
      "merchant": {
          "acceptor_id": "174030075991",
          "city": "NEW YORK",
          "country": "USA",
          "descriptor": "Sample Return",
          "mcc": "5812",
          "state": "NY"
      },
      "result": "APPROVED",
      "settled_amount": -7666,
      "status": "SETTLING",
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955"
    }
  ],
  "page": 1,
  "total_entries": 1,
  "total_pages": 1
}
approval_statusCan be approvals, declines, or all
pageFor pagination. The default is one
page_sizeFor pagination. The default value page size is 50 and the maximum is 1,000
beginDate string in the form YYYY-MM-DD, only transactions created after the specified date will be included
endDate string in the form YYYY-MM-DD, only transactions created before the specified date will be included
card_tokenFilters transactions associated with a specific card
transaction_tokenReturns a specific transaction
account_token (multi-account users only)Returns transactions associated with this account. Only applicable if using account enrollment. See Managing Identities for more information.

Simulate Transactions

See Simulating Transactions.

Transaction Webhooks

See Transaction webhooks definition.

Enumerations

Transaction.status

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

Transaction.result

APPROVED
CARD_PAUSEDCard state was paused at the time of authorization
CARD_CLOSEDCard state was closed at the time of authorization
GLOBAL_TRANSACTION_LIMITPlatform spend limit exceeded, contact [email protected]
GLOBAL_WEEKLY_LIMITPlatform spend limit exceeded, contact s[email protected]
GLOBAL_MONTHLY_LIMITPlatform spend limit exceeded, contact [email protected]
USER_TRANSACTION_LIMITUser-set spend limit exceeded
UNAUTHORIZED_MERCHANTMerchant locked card attempted at different merchant
SINGLE_USE_RECHARGEDSingle-use card attempted multiple times
BANK_CONNECTION_ERRORPlease reconnect a funding source
INSUFFICIENT_FUNDSPlease ensure the funding source is connected and up to date
MERCHANT_BLACKLISTThis merchant is disallowed on the platform
INVALID_CARD_DETAILSIncorrect CVV or expiry date
BANK_NOT_VERIFIEDPlease confirm the funding source
INACTIVE_ACCOUNTContact [email protected]
ACCOUNT_STATE_TRANSACTION_FAILContact [email protected]
UNKNOWN_HOST_TIMEOUTNetwork error, re-attempt the transaction
SWITCH_INOPERATIVE_ADVICENetwork error, re-attempt the transaction
FRAUD_ADVICETransaction declined due to risk
INCORRECT_PINPIN verification failed

Did this page help you?