API Basics

Authenticating

An API key is required to get started. Generate one on the Program settings page of the Lithic Dashboard.

Requests are authenticated with an API (secret) key with the following request header:

"Authorization: YOUR_API_KEY"

Example

curl --request GET \
     --url 'https://api.lithic.com/v1/cards' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_API_KEY'

Errors

You can use this information to diagnose failed transactions and fine-tune your exception-handling capabilities.

400

401

422

429

5xx

Lithic APIs may return HTTP 5xx errors in case of issues on Lithic's side. This always indicates a server-side error, and the specific HTTP error should not matter to the caller. The recommended action is to retry the request. If the issue persists, check our Status Page and contact [email protected].

General Notes

• Each entity is identified by its token.
• HTTP bodies must be valid JSON and the request header Content-Type must be application/json.
• Amounts are all integers. They are represented in the smallest unit of the associated currency (e.g., amount of 100 in USD is $1) unless specified otherwise.
• Any field we don’t have data for will show up as empty.
• All dates are RFC 3339 unless specified otherwise.
• Additional fields may be added to API response payloads. API users should ensure that any integrations and use of these responses can handle new fields at any time.

Pagination

📘

Auto-pagination helpers are available in our API libraries for easy navigation through all pages of a list.

Top-level API resources support bulk fetches through "list" API methods, such as list events, list disputes, and list settlement records. These methods have a common structure, taking at least page_size, starting_after, and ending_before as parameters.

Request Parameters:

page_size: The number of records to return in the API response.

starting_after: If provided, all items returned will have been created after the referenced object.

ending_before: If provided, all items returned will have been created before the referenced object.

The value provided for starting_after or ending_before should be a token of the type of resource being queried. For example, when querying the /disputes endpoint you would provide a dispute object's token as either the starting_after or ending_before value. To request the next set of results, you would provide the token of the last object in the current result as the starting_after value or the token of the first object in the current result as the ending_before value.

If neither starting_after or ending_before are provided, then the API will return the newest objects. Objects are always returned in reverse chronological order. starting_after and ending_before cannot be used together.

Response Parameters:

has_more: True when there are more records that match the API request. To access those items, update either the starting_after or ending_before parameters and send another request.

Pagination Example

// Example Request to GET /disputes using Pagination
{
  ... 
  "page_size": 5,
  "starting_after": "bf3022a8-4628-4417-b4db-e1ba72075a08",
  // All results returned will have been created after the referenced Dispute object.
}

// Response
{
  "data": [...], // 5 items returned because of the provided "page_size" in the request.
  "has_more": true // More items exist that match the query.
  // Change the "starting_after" to the token of the last object in data
  // to receive the next page of objects.
}

Transitioning from offset pagination to cursor-based pagination

If you are using an SDK, all Lithic client libraries now use cursor-based pagination by default. Update your libraries to the latest version to leverage this enhancement

If you are directly querying our APIs, to transition to cursor-based pagination, you would include the header X-Lithic-Pagination: cursor in your API requests and use starting_after or end_before query parameters instead of page. For example, assume you used the below offset pagination to get a list of transactions starting on page 2:

// Example Request to GET /transactions using offset
{
  ... 
  "page_size": 25,
  "page": 2,
}

// Response
{
  "data": [
    {
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
    	...
    },
    ...
  ], // 25 items returned because of the provided "page_size" in the request.
  "page": 2,
  "total_entries": 100,
  "total_pages": 4
}

To get the same results with offset pagination, you would traverse the list starting from the most recent entry:

// Example Request to GET /transactions using cursor-based
{
  ... 
  "page_size": 25,
    // no starting_after or ending_before provided since we are starting from the most recent event
}

// Response
{
  "data": [
    ...
    {
      "token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
    	...
    },
  ], // first 25 items returned in reverse chronological order
  "has_more": true
}

Then, you would take the token of the last object in the above result (079d1898-65f7-4d66-b0bc-172d2935a5fa) and use it in your next request as the value for starting_after. The results from this second request will match the results you retrieved from page 2 of the offset pagination request (assuming there has been no updates to the data):

// Example Request to GET /transactions using cursor-based
{
  ... 
  "page_size": 25,
  "starting_after": "079d1898-65f7-4d66-b0bc-172d2935a5fa" // continue onto "page 2" of the results
}

// Response
{
  "data": [
    {
      "token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
    	...
    },
    ...
  ], // next 25 items returned
  "has_more": true
}

Note that total_entries and total_pages fields will no longer be provided in the response to maintain consistent performance at scale.

Versioning and backwards compatibility

The Lithic API will not make backwards-incompatible changes (such as removing a field from the API) without reaching out to you first. We're continually making backwards-compatible changes to the API, however. A record of backwards-compatible changes can be found in our Changelog. Examples of backwards-compatible changes which we do not consider "breaking" include:

1. Adding new optional request parameters to existing API methods.
2. Adding new properties to existing API responses.
3. Changing the order of properties in existing API responses.
4. Adding new API resources or methods.
5. Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.