Guides
StatusDashboard

Guide to Lithic API Changes

In this guide, we discuss a few modifications we are making to our API in August and September 2022 that will apply to both our sandbox and production environments.

This guide is intended to help users navigate the upcoming changes to the Lithic API.

For the Transaction Schema Modification and Simulating Transactions Modification, these changes will be effective in Production on September 27, 2022 at 17:00 UTC.

For the API Endpoint Modifications detailed below, the existing endpoints will continue to work. Given new feature development will be focused on the new endpoints, we encourage you to explore them and migrate integrations at a time that makes sense for you.

Transaction Schema Modification (effective Sep 27, 2022 in Production and August 30, 2022 in Sandbox)

transaction.events[].amount to become signed

  • Currently, amount field within the events array within the Transaction schema are unsigned amounts
  • In both the responses from transactions endpoints and in the Transaction Webhook message, this will become a signed field (positive amounts are debits, negative amounts are credits) and consistent with how the top-level transaction.amount appears
  • To defend against this, users can wrap an abs() function around the events[].amount until they are ready to handle negative amounts in the schema
  • For consistency, once the change is deployed, all transactions, including ones generated before September 27 17:00 UTC, will appear with the new signed amount.

Simulating Transactions Modification (effective Sep 27, 2022)

Declined simulated transactions to return 200 response

  • Previously, if a simulated transaction (created via the POST /simulate/authorize endpoint) was declined, a 422 response code would be returned
  • With this update, simulated transactions that are declined will return a 200 response to indicate a “successful” decline

API Endpoint Modifications

Accounts

Get Accounts: GET /account -> GET /accounts/{account_token}

  • Resource naming is changing from account to accounts
  • account_token should be passed in as a path parameter and not as a query parameter
  • account_token in the response will be renamed to token
  • Account configurations will only be returned under a "data" field if multiple account_tokens are included in the response

Update Accounts: POST /account/state and POST /account/limit -> PATCH /accounts/{account_token}

  • Resource naming is changing from account to accounts
  • Instead of calling two separate endpoints to change an account's state and account's spend limits, those operations are now consolidated under a new "Update Account" endpoint
  • Operation will change from a POST to a PATCH, meaning partial updates to the account details are permitted and only parameters that are passed in will be updated

Creating Account Holders: POST enroll/consumer -> POST /account_holders

  • Instead of using a dedicated endpoint to enroll consumer end-users onto the Lithic platform, all account creation calls (whether using Lithic's KYCaaS, KYBaaS, or a BYO option) will take place via a "Create Account Holders" endpoint
  • The new endpoint does not require any additional information requested beyond what is required for the existing "Enroll User" process. Customers currently using the type = PRECHECKED workflow should use the renamed KYC_BYO workflow, and customers using the type = BASIC workflow should use the renamed KYC_BASIC workflow
  • Upon successful creation of an account holder (e.g.,, successful KYC if using Lithic KYCaaS, successful input of all required parameters if using BYO KYC), an associated account_token will be returned

Cards

List Cards: GET /card -> GET /cards

  • Resource naming is changing from card to cards

Get Card: GET /card -> GET /cards/{card_token}

  • Resource naming is changing from card to cards
  • card_token should be passed in as a path parameter and not as a query parameter
  • GET /cards/{card_token} will return a single card object

Create Card: POST /card -> POST /cards

  • Resource naming is changing from card to cards

Update Card: PUT /card -> PATCH /cards/{card_token}

  • Resource naming is changing from card to cards
  • card_token should be passed in as a path parameter and not as a body parameter
  • Operation will change from a PUT to a PATCH, meaning partial updates to the card details are permitted and only parameters that are passed in will be updated

Reissue Card: POST /card/reissue -> POST /cards/{card_token}/reissue

  • Resource naming is changing from card to cards
  • card_token to be reissued should be passed in as a path parameter and not as a body parameter

Provision Card (Digital Wallet): POST /card/provision -> POST /cards/{card_token}/provision

  • Resource naming is changing from card to cards
  • card_token to be provisioned should be passed in as a path parameter and not as a body parameter

Transactions

List Transactions: GET /transaction -> GET /transactions

  • Resource naming is changing from transaction to transactions
  • card_token and result (i.e., APPROVED or DECLINED) will now be accepted as query parameters

Get Specific Transaction: GET /transaction/{transaction_filter} -> GET /transactions/{transaction_token}

  • Resource naming is changing from transaction to transactions
  • Endpoint operation will be simplified to return a single transaction as specified by the transaction_token; previous use of this endpoint to filter for approved or declined transactions can be done via the "List Transactions" endpoint above

Enroll ASA: POST /authstream/enroll -> POST /auth_stream

  • Resource naming is changing from authstream to auth_stream
  • The "enroll" portion of the endpoint URI is no longer needed

Disenroll ASA: POST /authstream/disenroll -> DELETE /auth_stream/

  • Resource naming is changing from authstream to auth_stream
  • Instead of a POST call, disenrolling from ASA will now be done with a DELETE call

Funding Sources

List Funding Sources: GET /fundingsource -> GET /funding_sources

  • Resource naming is changing from fundingsource to funding_sources
  • The list of funding sources will be under a "data" field for consistency

Add Funding Source: POST /fundingsource/bank and POST /fundingsource/plaid -> POST /funding_sources

  • Resource naming is changing from fundingsource to funding_sources
  • Instead of calling two separate endpoints to add a bank funding source and a funding source via Plaid, those operations are consolidated under a new "Add Funding Source" endpoint

Update Bank Account: PUT /fundingsource/bank -> PATCH /funding_sources/{funding_source_token}

  • Resource naming is changing from fundingsource to funding_sources
  • funding_source_token should be passed in as a path parameter and not as a body parameter

Verify Bank Account: POST /fundingsource/bank/validate -> POST /funding_sources/{funding_source_token}/verify

  • Resource naming is changing from fundingsource to funding_sources
  • funding_source_token should be passed in as a path parameter and not as a body parameter

Updated over 2 years ago