Transactions
Learn more about transactions.
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,
"cardholder_authentication": CardholderAuthentication,
"acquirer_reference_number": String
}
card | See Card Schema. Note that this field will be removed and replaced with a card_token field in Sandbox on January 4 and in Production on February 8, 2023. Please refer to this page for more information. |
amount | Authorization amount of the transaction (in cents), including any acquirer fees. 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, including any acquirer fees. 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 (smallest unit), including any acquirer fees. |
merchant_authorization_amount | Analogous to the "authorization_amount" property, but will represent the amount in the transaction's local currency (smallest unit), including any acquirer fees. |
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, including any acquirer fees.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.Note that this field will be removed in Sandbox on January 4 and in Production on February 8, 2023. Please refer to this page for more information. |
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, including any acquirer fees. This may change over time. |
status | PENDING , VOIDED , SETTLING , SETTLED , BOUNCED , DECLINED .Note that BOUNCED and SETTLING will be removed, and EXPIRED will be added, in Sandbox on January 4 and in Production on February 8, 2023. Please refer to this page for more information. |
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. |
cardholder_authentication | See Cardholder Authentication Schema definition below. |
acquirer_reference_number | Unique identifier assigned to a transaction by the acquirer that can be used in dispute and chargeback filing. This is only populated once a transaction has been cleared, and is not available for all transactions. A single transaction can have multiple ARNs if the merchant sends multiple clearings. These are most commonly seen in the case of e-commerce (e.g., where a merchant clears purchases each time goods within a larger order are shipped) and travel (e.g., where an airline sends a unique clearing record per passenger per flight segment). Known cases where ARN will not be present are: automated fuel dispenser (AFD) transactions, single message transactions, and authorizations that are never cleared. |
Event Schema
{
"amount": Integer,
"created": String,
"result": Enum,
"type": Enum,
"token": String
}
A single card transaction may include multiple events that affect the transaction state and lifecycle.
amount | Amount of the transaction event, including any acquirer fees. Debits (event types AUTHORIZATION_ADVICE and CLEARING will appear as positive amounts and credits (event types VOID and RETURN ) will appear as negative amounts. Event type AUTHORIZATION can be either a debit or a credit depending on the authorization type (e.g., purchase authorization vs. refund authorization). |
created | Date and time this event entered the system. |
result | APPROVED or decline reason. See below for full enumeration. |
type | AUTHORIZATION , AUTHORIZATION_ADVICE , CLEARING , VOID , RETURN .Note that a few changes will be applied to the event type enums in Sandbox on January 4 and in Production on February 8, 2023. The following types will be added: FINANCIAL_AUTHORIZATION , CREDIT_AUTHORIZATION , FINANCIAL_CREDIT_AUTHORIZATION , AUTHORIZATION_REVERSAL , AUTHORIZATION_EXPIRY , RETURN_REVERSAL , BALANCE_INQUIRY , and CREDIT_AUTHORIZATION_ADVICE . The following type will be removed: VOID . Please refer to this page for more information. |
token | Globally unique identifier for the event. |
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. |
Cardholder Authentication Schema
Lithic provides metadata on authentication attempts. These fields can be used to determine if cardholder authentication was performed prior to the authorization being submitted by the merchant. Cardholder authentication could happen via:
- 3-D Secure programs, such as Mastercard Secure Code or Identity Check
- Digital Secure Remote Payments (DSRP) tokenized payments via Apple Pay wallets
If the cardholder is authenticated or the merchant attempts authentication and the issuer declines to verify, liability shift may apply. If it does, the merchant no longer has liability for the transaction and it cannot be charged back for fraud.
{
"verification_attempted": Enum,
"verification_result": Enum,
"liability_shift": Enum,
"3ds_version": Enum,
"acquirer_exemption": Enum
}
verification_attempted | - NONE : Cardholder verification was not attempted. Authentication was performed via a frictionless flow, not attempted, or via standin risk-based authentication (RBA)- OTHER : An undefined method, such as a previously challenged recurring transaction, was used to verify the cardholder |
verification_result | - SUCCESS : Authentication Verification Successful- FRICTIONLESS : Attempts Processing Performed; Not Authenticated/Verified, but merchant attempted authentication/verification is provided- NOT_ATTEMPTED : A 3DS attempt was not made for this transaction. |
liability_shift | - NONE : Liability has not shifted to the issuer (i.e. the merchant is liable)- 3DS_AUTHENTICATED : Fully authenticated (possibly recurring) transaction. Liability shift applies- TOKEN_AUTHENTICATED : Tokenized Payment with validated cryptography, possibly recurring, liability shift applies |
3ds_version | 3DS Protocol Version. Note that this field may appear as three_ds_version in some of Lithic's client libraries.- 1 : 3DS V1 was used.- 2 : 3DS V2 (EMV) was used.- null : No 3DS was used. |
acquirer_exemption | Will always be NONE , reserved for future use.- NONE : No exemption applied |
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"
}
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
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 and events[*].result
ACCOUNT_STATE_REVIEW | Account (to which the card used in the transaction belongs) is under review; relevant to Starter customers only |
ACCOUNT_STATE_TRANSACTION_FAIL | Contact [email protected] |
APPROVED | Successful transaction |
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 |
DECLINED | Transaction was declined for a reason not captured by the other listed reasons |
FRAUD_ADVICE | Transaction declined due to risk-related reasons |
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] |
IGNORED_TTL_EXPIRY | Authorization could not be processed by the Lithic platform in time |
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 |
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 |
Updated 9 days ago