# Getting Started

# Introduction

The Lithic developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through a REST API and transaction webhooks.

Some functionality is only available with an issuing plan and is marked with Issuing or requires an enhanced setup and is marked with Enterprise in the documentation. All functionality is available for free in the sandbox.

If you're interested in features outside of what's documented here, we provide custom integrations. Please reach out to api@lithic.com for more information.

# Authentication

An API key is required to get started. Generate one in the account page (opens new window).

Dates and times are returned in ISO 8601 format. Time zone is UTC.

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

"Authorization:api-key YOUR_API_KEY"

Example curl request to return cards:

curl https://api.lithic.com/v1/card -H "Authorization:api-key YOUR_API_KEY"

# General Notes

There are seven types of objects: AccountConfiguration, Card, EmbedRequest, Event, FundingAccount, Merchant and Transaction.

Each entity is identified by its UUID token.

HTTP bodies must be valid json and the request header Content-Type must be application/json.

Amounts are all integers. They represent the number in cents (dollar amount is amount/100).

Any field we don’t have data for will show up as empty.

API GET responses are returned in a pagination wrapper in the form:

  "data": [
  "page": Integer,
  "total_entries": Integer,
  "total_pages": Integer

Where page is the page number returned to the user, total_entries is the number of entries returned by the query, and total_pages is the number of pages given the pagination settings.

# Managing Identities Enterprise

A single API key can manage a portfolio of end-users, each with their own funding sources, cards and transactions. End-users are onboarded to through the enrollment endpoint.

After the first end-user is enrolled in the production environment, all subsequent API calls must include a URI parameter ?account_token= indicating which end-user this API request is on behalf of.

The reason for this behavior change is because upon initial provisioning, the API Key maps 1:1 to an account (specifically, your account). After calling POST /enroll, the API key mapping becomes 1:many, so the API requires an account_token parameter to indicate which account, within the portfolio of accounts, to perform an action on behalf of.

If one or more end-users have been enrolled and no account_token argument is supplied, an API error will be returned.

# Compliance

In order to comply with US laws and regulations, including the Bank Secrecy Act (BSA), Money Laundering Control Act, U.S. Treasury Department of Foreign Assets Control Regulations (OFAC) FinCEN Rules and Regulations (Code of Federal Regulations Title 31, Chapter X) and various provisions of the USA PATRIOT Act of 2001, the identity of all end user’s must successfully pass the Lithic Customer Identification Program (CIP) before they can transact. Lithic will be unavailable to persons whose identity cannot be reasonably verified. Access will not be granted until verification is successfully completed.

The enrollment endpoint runs the candidate enrollment through the Lithic CIP and returns a pass or failure. A "pass" indicates that the identity was successfully verified and the end-user can transact. Failures can be one of two types:

(1) The identity could not be verified; or (2) The identity was verified but ineligible to enroll Failures of type (1) are able to be retried and may be successful if corrected data is re-submitted (ie. fixed typographical error).

Failures of type (2) should not be retried and the candidate enrollment should be abandoned.

Using the enrollment endpoint and receiving successful responses is an important part of ensuring your card program is compliant with relevant government and banking regulations. Please note that attempts to bypass the CIP controls or attempting to allow end-users to affect transactions before receiving a successful CIP response is a violation of the Lithic terms of service and may result in service suspension.

# Sandbox

We offer a free sandbox environment at https://sandbox.lithic.com (opens new window) that provides all the functionality of https://api.lithic.com (opens new window) with test payment card numbers. The sandbox requires a separate API key that is also available in the account page (opens new window). We highly recommend you develop and test your app against the sandbox — you are responsible for all financial activity on api.lithic.com associated with your API key.

# Transaction Simulator

Because the sandbox environment is not connected to payment networks, it cannot receive card transactions. The sandbox environment has additional endpoints to simulate transaction events originating from a merchant acquirer. Simulated transaction events will trigger transaction webhooks and will be returned in subsequent GET /v1/transaction responses.