Transaction Schema

{
  "card": Card,
  "amount": Integer,
  "authorization_amount": Integer,
  "merchant_amount": Integer,
  "merchant_authorization_amount": Integer,
  "merchant_currency": String,
  "acquirer_fee": Integer,
  "created": String,
  "events": [
      Event
  ],
  "funding": [
      {
       "amount": Integer,
       "token": String,
       "type": String
      }
  ],
  "merchant": Merchant,
  "network": String,
  "result": String,
  "settled_amount": Integer,
  "status": String,
  "token": String,
  "authorization_code": String
}


card	See Card Schema.
amount	Authorization amount of the transaction in the currency's smallest unit (e.g., cents for USD). This may change over time, and will represent the settled amount once the transaction is settled.
authorization_amount	Authorization amount (in cents) of the transaction in the currency's smallest unit (e.g., cents for USD). This amount always represents the amount authorized for the transaction, unaffected by settlement.
merchant_amount	Analogous to the "amount" property, but will represent the amount in the transaction's local currency.
merchant_authorization_amount	Analogous to the "authorization_amount" property, but will represent the amount in the transaction's local currency.
merchant_currency	3-digit alphabetic ISO 4217 code for the local currency of the transaction.
acquirer_fee	Fee (in the currency's smallest unit) assessed by the merchant and paid for by the cardholder. Will be zero if no fee is assessed. Rebates may be transmitted as a negative value to indicate credited fees.
created	Date and time when the transaction first occurred.
events	A list of all events that have modified this transaction.
funding	A list of objects that describe how this transaction was funded, with the `amount` represented in the currency's smallest unit. A reference to the funding source for the card that made this transaction may appear here and the `token` will match the `token` for the funding source in the `card` field. If any promotional credit was used in paying for this transaction, its `type` will be `PROMO`.
merchant	See Merchant Schema definition below.
network	Card network of the authorization. Can be `INTERLINK`, `MAESTRO`, `MASTERCARD`, `VISA`, or `UNKNOWN`.
result	`APPROVED` or decline reason. See below for full enumeration.
settled_amount	Amount (in cents) of the transaction that has been settled. This may change over time.
status	`PENDING`, `VOIDED`, `SETTLING`, `SETTLED`, `BOUNCED`, `DECLINED`.
token	Globally unique identifier for the transaction.
authorization_code	A fixed-width 6-digit numeric identifier that can be used to identify a transaction with networks.

Event Schema

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

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


amount	Amount of the transaction event. This is always a positive value, unlike the transaction amount in the Transaction Schema. Whether the amount is a debit or credit depends on the event type: `AUTHORIZATION`, `AUTHORIZATION_ADVICE`, and `CLEARING` are debits; `VOID` and `RETURN` are credits.
created	Date and time this event entered the system.
result	`APPROVED` or decline reason. See below for full enumeration.
token	Globally unique identifier for the event.
type	`AUTHORIZATION`, `AUTHORIZATION_ADVICE`, `CLEARING`, `VOID`, `RETURN`.

Merchant Schema

{
  "acceptor_id": String,
  "city": String,
  "country": String,
  "descriptor": String,
  "mcc": String,
  "state": String
}


acceptor_id	Identifier for the payment card acceptor.
city	City of card acceptor.
country	Country of card acceptor.
descriptor	Short description of card acceptor.
mcc	Merchant category code.
state	Geographic state of card acceptor.

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": {
          "created": "2020-07-15T17:48:48Z",
          "token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
          "last_four": "6749",
          "hostname": "",
          "memo": "card 2",
          "type": "VIRTUAL",
          "spend_limit": 0,
          "spend_limit_duration": "TRANSACTION",
          "state": "OPEN",
          "funding": {
              "created": "2020-07-08 17:57:36",
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING",
              "state": "ENABLED",
              "nickname": "",
              "account_name": "Sandbox",
              "last_four": "5263"
          },
          "auth_rule_tokens": []
      },
      "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"
          }
      ],
      "funding": [
          {
              "amount": -7666,
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING"
          }
      ],
      "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": {
          "created": "2020-07-15T17:48:48Z",
          "token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
          "last_four": "6749",
          "hostname": "",
          "memo": "card 2",
          "type": "VIRTUAL",
          "spend_limit": 0,
          "spend_limit_duration": "TRANSACTION",
          "state": "OPEN",
          "funding": {
              "created": "2020-07-08 17:57:36",
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING",
              "state": "ENABLED",
              "nickname": "",
              "account_name": "Sandbox",
              "last_four": "5263"
          },
          "auth_rule_tokens": []
      },
      "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"
          }
      ],
      "funding": [
          {
              "amount": -7666,
              "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
              "type": "DEPOSITORY_CHECKING"
          }
      ],
      "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"
}


transactiontoken (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.

Transaction Webhooks

See Transaction webhooks definition.

Enumerations

Transaction.status


BOUNCED	There was an error settling the transaction against the funding source. Your API account may be disabled
DECLINED	The transaction was declined
PENDING	Authorization is pending completion from the merchant
SETTLING	The merchant has completed the transaction and the funding source is being debited
SETTLED	The transaction is complete
VOIDED	The merchant has voided the previously pending authorization

Transaction.result


ACCOUNT_STATE_TRANSACTION_FAIL	Contact [email protected]
APPROVED		Successful transaction; no reason to decline
BANK_CONNECTION_ERROR	Please reconnect a funding source
BANK_NOT_VERIFIED	Please confirm the funding source
CARD_PAUSED	Card state was paused at the time of authorization
CARD_CLOSED	Card state was closed at the time of authorization
FRAUD_ADVICE	Transaction declined due to risk
GLOBAL_MONTHLY_LIMIT	Platform spend limit exceeded, contact [email protected]
GLOBAL_TRANSACTION_LIMIT	Platform spend limit exceeded, contact [email protected]
GLOBAL_WEEKLY_LIMIT	Platform spend limit exceeded, contact [email protected]
INACTIVE_ACCOUNT	Contact [email protected]
INCORRECT_PIN	PIN verification failed
INSUFFICIENT_FUNDS	Please ensure the funding source is connected and up to date
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
MERCHANT_BLACKLIST	This merchant is disallowed on the platform
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