Guide to Q1 2023 Lithic API Changes

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`

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

Similar 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

We'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
`BOUNCED` and `SETTLING` will be removed as statuses. Any transactions that previously were in this state will be remapped to `SETTLED`.	No action needed.
`VOIDED` status will be broken out into two statuses for enhanced visibility: - `VOIDED` will continue to exist to indicate that the merchant reversed the authorization. - `EXPIRED` will be added to indicate that Lithic reversed the authorization as it has passed its expiration time.	Integrations should be ready to handle `EXPIRED` as a new status enum. Refer to this section of our documentation for when the status may be surfaced. To prepare for this, users can remap `EXPIRED` to `VOIDED` until they are ready to handle the new status.

Change #4: Modifying `events[*].type` enums

Similar 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
`AUTHORIZATION` event type will be broken out into four types for enhanced visibility: - `AUTHORIZATION` will continue to exist to indicate a purchase authorization. - `FINANCIAL_AUTHORIZATION` will be added to indicate a request from a merchant to debit funds without additional clearing. - `CREDIT_AUTHORIZATION` will be added to indicate a refund or credit authorization from a merchant. - `FINANCIAL_CREDIT_AUTHORIZATION` will be added to indicate a request from a merchant to refund or credit funds without additional clearing.	Refer to this section of our documentation for when `FINANCIAL_AUTHORIZATION` may be surfaced. Refer to this section of our documentation about when `CREDIT_AUTHORIZATION` may be surfaced. Refer to this section of our documentation about when `FINANCIAL_CREDIT_AUTHORIZATION` may be surfaced. To prepare for this, users can remap the new event types to `AUTHORIZATION` until they are ready to handle them.
`VOID` event type will be broken out into two types for enhanced visibility: - `AUTHORIZATION_REVERSAL` will indicate that the authorization was reversed by the merchant. - `AUTHORIZATION_EXPIRY` will indicate that the authorization has expired and reversed by Lithic.	Refer to this section of our documentation for when `AUTHORIZATION_REVERSAL` may be surfaced. Refer to this section of our documentation about when `AUTHORIZATION_EXPIRY` may be surfaced. To prepare for this, users can remap the new event types to `VOID` until they are ready to handle them.
`RETURN` event type will be broken out into two types for enhanced visibility: - `RETURN` will continue to exist to indicate that a refund has been processed on the transaction. - `RETURN_REVERSAL` will be added to indicate that a refund has been reversed (e.g., when a merchant reverses an incorrect refund).	Refer to this section and this section of our documentation for when `RETURN_REVERSAL` may be surfaced. To prepare for this, users can remap the new event type to `RETURN` until they are ready to handle it.
`BALANCE_INQUIRY` event type will be added. This will be used to indicate that a balance inquiry (typically a $0 authorization) has occurred on a card.	Refer to this section of our documentation for when `BALANCE_INQUIRY` may be surfaced. To prepare for this, users can remap the new event type to `AUTHORIZATION` (or `FINANCIAL_AUTHORIZATION` if part of the financial authorization beta) until they are ready to handle it.
`CREDIT_AUTHORIZATION_ADVICE` event type will be added. This will be used to indicate that a credit authorization was approved on your behalf by the network.	Refer to this section of our documentation for when `CREDIT_AUTHORIZATION_ADVICE` may be surfaced.

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
Simulate void transaction endpoint will be updated to include new types of AUTHORIZATION_REVERSAL or AUTHORIZATION_EXPIRY available for simulation (instead of sending an event type of VOID)
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.

Deploy Dates

Impacted Surfaces

Current vs. New Transaction Schema

Change #1: Replacing the card object with a card_token

Change #2: Removing funding array

Change #3: Modifying transaction.status enums

Change #4: Modifying events[*].type enums

Testing Changes in Sandbox

Change #1: Replacing the `card` object with a `card_token`

Change #2: Removing `funding` array

Change #3: Modifying `transaction.status` enums

Change #4: Modifying `events[*].type` enums