Guide to Q1 2023 Lithic API Changes
In this guide, we discuss a few improvements we are making to our API in January and February 2023 that will apply to both the sandbox and production environments.
This guide is intended to help users navigate the upcoming changes to the Lithic API.
Deploy Dates
- [Deploy completed] Sandbox Environment: Effective January 4, 2023 (Wednesday) ~17:00 UTC / Noon EST
- [Deploy completed] Production Environment: Effective February 8, 2023 (Wednesday) ~17:00 UTC / Noon EST
Impacted Surfaces
As these changes all apply to the transaction object, the new schema will be evident across two surfaces:
- The transaction webhook
- The response payload from the transactions API (
GET /transactions
)
Note that after the deploy dates, all transactions (historical and new) will be returned with the new schema. Our client libraries will also be updated to reflect the changes. There will be no impact to the schema of ASA requests.
An updated version of our transaction flow page is available that articulates the possible transaction lifecycle paths you can expect with these changes incorporated.
Current vs. New Transaction Schema
{
"card_token": String, // This field is new
"amount": Integer,
"authorization_amount": Integer,
"merchant_amount": Integer,
"merchant_authorization_amount": Integer,
"merchant_currency": String,
"acquirer_fee": Integer,
"created": String,
"events": [
Event
], // Note modifications to event.type enums detailed below
"merchant": Merchant,
"network": String,
"result": String,
"settled_amount": Integer,
"status": String, // Note modifications to status enums detailed below
"token": String,
"authorization_code": String,
"cardholder_authentication": CardholderAuthentication,
"acquirer_reference_number": String
}
{
"card": Card, // This object will be removed
"amount": Integer,
"authorization_amount": Integer,
"merchant_amount": Integer,
"merchant_authorization_amount": Integer,
"merchant_currency": String,
"acquirer_fee": Integer,
"created": String,
"events": [
Event
], // event.type enum values contained in this array will be modified
"funding": [
{
"amount": Integer,
"token": String,
"type": String
}
], // This array will be removed
"merchant": Merchant,
"network": String,
"result": String,
"settled_amount": Integer,
"status": String, // These enum values will be modified
"token": String,
"authorization_code": String,
"cardholder_authentication": CardholderAuthentication,
"acquirer_reference_number": String
}
Change #1: Replacing the card
object with a card_token
card
object with a card_token
We've heard your feedback that passing through sensitive information contained in the card
object was introducing unneeded complexity to your PCI data handling and storage. We're simplifying the data being passed through the transaction object so that you will still know which card a transaction is associated with, without having to receive and process more sensitive data than needed.
What's changing | How to prepare for this change |
---|---|
The card object (containing fields such as created, last_four, spend_limit, etc.) will be removed. The card_token associated with the transaction will be added in its place. | Integrations parsing the card object can instead parse the card_token , and call the GET /cards endpoint for the latest information associated with the card. |
Change #2: Removing funding
array
funding
arraySimilar to the above change, we are removing funding
array to simplify the schema and limit fields to those that are most relevant to our users.
What's changing | How to prepare for this change |
---|---|
The funding array describing how the card associated with the transaction was funded will be removed. | Integrations parsing the funding array can instead parse the card_token , and call the GET /cards endpoint for the latest funding source associated with the card. |
Change #3: Modifying transaction.status
enums
transaction.status
enumsWe've received feedback that more granular transaction status values will better equip you to understand the transaction lifecycle and where a transaction stands.
What's changing | How to prepare for this change |
---|---|
| No action needed. |
| Integrations should be ready to handle |
Change #4: Modifying events[*].type
enums
events[*].type
enumsSimilar to the above change, we've heard your feedback that more detailed event types would better reflect the various events that can occur on a given transaction.
What's changing | How to prepare for this change |
---|---|
| Refer to this section of our documentation for when |
| Refer to this section of our documentation for when |
| Refer to this section and this section of our documentation for when |
| Refer to this section of our documentation for when |
| Refer to this section of our documentation for when |
Testing Changes in Sandbox
Simulations for these changes will be available in Sandbox beginning on January 4, 2023.
- Simulate authorization endpoint will be updated in two ways:
- It will have a new
BALANCE_INQUIRY
status available for simulation - It will begin sending the more detailed
*_AUTHORIZATION
statuses as selected for simulation
- It will have a new
- Simulate void transaction endpoint will be updated to include new
types
ofAUTHORIZATION_REVERSAL
orAUTHORIZATION_EXPIRY
available for simulation (instead of sending an event type ofVOID
) - A new simulate return reversal endpoint will be added to allow for testing the new event type of
RETURN_REVERSAL
- A new simulate credit authorization advice endpoint will be added to allow for testing the new
CREDIT_AUTHORIZATION_ADVICE
event type - All of the transaction simulation endpoints will begin returning the updated transaction schema
We sincerely appreciate your attention to these changes. If you have any questions, please contact our support team.
Updated 16 days ago