Issuer Processor: Lithic

This article will guide you through a basic issuer processor integration using Lithic.


The Canopy Lithic Integration allows Canopy to automatically wrap calls to the Lithic API when you use Canopy as normal.

  • When a borrower is onboarded; Canopy will automatically create their corresponding card in Lithic
  • When the borrower uses their card, Canopy will subscribe to the authorization request and handle authorization based on the available credit on the account.
  • When transaction states change in Lithic, Canopy’s ledger will update those transaction states in sync.

From Your Perspective

  1. You set your Lithic API keys in Canopy
  2. You onboard borrowers into Canopy as normal per our core workflows
    1. When onboarding borrowers, you need to pass a few extra details necessary for card creation in Lithic
  3. You do not need to write any code to call Create a charge for a specific account or Update an existing line item (i.e. the charge) in Canopy; we will handle this by subscribing to Lithic’s webhooks
  4. Canopy supports all Authorization and Settlement transaction types (such as Partial Authorization and Incremental Clearing) as well as Adjustment Events (such as Merchant Credits and Dispute Handling)
    1. Whenever an authorization request is processed by Canopy, our system creates a new line item and sets the Line Item Status as AUTHORIZED.
      (To better understand line item statuses in Canopy, check out Line Item Types )
    2. Updates to this authorization request are sent by Lithic and processed by Canopy, mapping the various transaction states in Lithic to internal Canopy line item statuses
      1. For example, SETTLED authorizations map to VALID line items in Canopy
      2. VOIDED and EXPIRED to line item VOID
  5. Canopy automatically updates the transaction amount based on whatever was received from Lithic during settlement.
  6. Canopy is also able to perform a CHARGE_REVERSAL whenever Lithic suggests the authorization needs to be reversed.

Step 1: API Keys

There is only one easy step to getting the issuer-processor integration set up:

To get started, Generate a set of API keys in the Lithic dashboard, and store these in Canopy by passing a lithic_config to the PUT /organizations/issuer_processors endpoint in Canopy.

Canopy is now equipped to communicate with Lithic on your behalf.
That’s it! - Your Lithic Integration is now running. You can use Canopy as normal.
On an ongoing basis, you may choose to modify the state of current cards or create multiple cards for a customer. You may do so via our Cards API endpoints:

Step 2: Create Entities

Here’s what to expect now that your integration is set up:


  • In all Create a new account requests to Canopy, you should now expect to see an issuer_processor and cards section in the response
  • In the GET requests to all accounts, you should now see issuer processor and card details in the response

Line Items

In all line items created by the Lithic integration, you should see issuer_processor_metadata object included in the GET and POST requests that include transaction data. E.g. Create a charge for a specific account

Lithic Dashboard

You should see all cards created by Canopy, and all transactions in your Lithic Dashboard whenever customers use their cards.