Guides
StatusDashboard

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

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 changingHow 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 changingHow 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 changingHow 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 changingHow 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.

Updated about 2 months ago

Did this page help you?