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 support.lithic.com.

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

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: A cursor for pagination. Provide an item's token to fetch the next page of results that appear after this item in the list.
• ending_before: A cursor for pagination. Provide an item's token to fetch the previous page of results that appear before this item in the list.

To navigate through pages:

• To get the next page: use starting_after with the token of the last item in your current results
• To get the previous page: use ending_before with the token of the first item in your current results

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 (newest first). 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",
  // Returns the next page of results (older items) after this dispute in the list.
}

// Response
{
  "data": [...], // 5 items returned because of the provided "page_size" in the request.
  "has_more": true // More items exist that match the query.
}

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.

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.