> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

# Lithic

## Overview

Lithic provides virtual card infrastructure that integrates seamlessly with the Mercoa Virtual Card Agent. The integration uses Lithic's embedded card iframe technology to securely display and interact with virtual cards.

## Integration Setup

### Enable Lithic in Your Account

To start using Lithic with the Virtual Card Agent:

1. Create an account at [lithic.com](https://lithic.com)
2. Complete the application process and KYB verification
3. Set up your card program in the Lithic dashboard
4. Obtain your API keys
5. Generate embed requests and HMAC signatures for card display

### Create Virtual Card

Create virtual cards for specific invoices:

```javascript
const virtualCard = await lithic.cards.create({
  type: 'VIRTUAL',
  program_id: cardProgram.token,
  spend_controls: {
    spend_limit: invoice.amount * 100, // Amount in cents
    spend_limit_duration: 'TRANSACTION'
  },
  state: 'ACTIVE',
  metadata: {
    invoice_id: invoice.id,
    vendor_id: invoice.vendor_id
  }
});
```

> **Note**
>
> This is just an example, please refer to the [Lithic documentation](https://docs.lithic.com/docs/quick-start-create-card) for more information.

## API Integration

The Lithic integration with the Virtual Card Agent provides a secure, automated workflow for processing virtual card payments using Lithic's embedded card iframe technology.

### How It Works

The integration follows a secure workflow where your Lithic virtual card is embedded and used to process payments through the Virtual Card Agent:

```mermaid
graph LR
    A[Lithic Card Token] --> B[Generate Embed Request]
    B --> C[Create HMAC Signature]
    C --> D[Mercoa API]
    D --> E[Agent + Lithic iFrame]
    E --> F[Payment Gateway]
```

**Process Flow:**

1. Create a Lithic virtual card with spending controls matching the invoice amount
2. Generate an embed request with card token and styling configuration
3. Create an HMAC signature for the embed request using your Lithic API key
4. Call the Mercoa API with the embed request and HMAC signature
5. The agent displays the card securely through Lithic's iframe technology
6. Card details are extracted and used to complete payment through the vendor's payment gateway
7. Receipt and confirmation details are captured for reconciliation

### API Request Structure

When using Lithic with the Virtual Card Agent, your API request should include:

```json
{
  "type": "html",
  "html": "<html><body><h1>Invoice Details</h1><a href=\"https://www.payment-gateway.com/invoice/123123\">Pay Invoice</a></body></html>",
  "cardDetails": {
    "type": "lithic",
    "firstName": "John",
    "lastName": "Doe",
    "postalCode": "12345",
    "country": "US",
    "cardType": "credit",
    "embedRequest": "eyJ0b2tlbiI6ImQ2ODkxZGI2LThlNzgtNGYxYS1iMTUyLTk5OTc3N2VjM2Q4MiIsImNzcyI6Imh0dHBzOi8vc3RvcmFnZS5nb29nbGVhcGlzLmNvbS9tZXJjb2EtcGFydG5lci1sb2dvcy9saXRoaWMuY3NzIn0=",
    "hmac": "lEmiyyZnWuOpx8qO3g9cDGeRj7L30/SbRdvowxyCmfg="
  }
}
```

### Field Descriptions

#### Card Details Object

| Field          | Type   | Required | Description                                |
| -------------- | ------ | -------- | ------------------------------------------ |
| `type`         | string | Yes      | Must be `"lithic"`                         |
| `firstName`    | string | Yes      | Cardholder's first name                    |
| `lastName`     | string | Yes      | Cardholder's last name                     |
| `postalCode`   | string | Yes      | Billing address postal code                |
| `country`      | string | Yes      | Billing address country (ISO code)         |
| `cardType`     | string | No       | Card type (`"credit"` or `"debit"`)        |
| `embedRequest` | string | Yes      | Base64-encoded embed request JSON          |
| `hmac`         | string | Yes      | HMAC-SHA256 signature of the embed request |

#### Embed Request and HMAC Signature Generation

The `embedRequest` should be a base64-encoded JSON object containing:

```javascript
const embedRequestObj = {
  token: "d6891db6-8e78-4f1a-b152-999777ec3d82", // Your Lithic card token
  css: "https://storage.googleapis.com/mercoa-partner-logos/lithic.css", // Optional styling
  expiration: "2024-12-31T23:59:59Z", // Optional expiration time
  target_origin: "https://yourdomain.com" // Optional target origin for iframe communication
};

const embedRequest = Buffer.from(JSON.stringify(embedRequestObj)).toString('base64');
```

Generate the HMAC signature using your Lithic API key:

```javascript
const crypto = require('crypto');

const hmac = crypto
  .createHmac('sha256', process.env.LITHIC_API_KEY)
  .update(JSON.stringify(embedRequestObj))
  .digest('base64');
```

> **Note**
>
> This is just an example, please refer to the [Lithic documentation](https://docs.lithic.com/docs/embedded-card-ui) for more information.

### Security Considerations

* **Set card expiration** to limit the time window for card usage
* **Monitor card usage** through Lithic's dashboard and webhook events
* **Enable logging** for all virtual card operations to maintain an audit trail

## Best Practices

### 🔐 Security

* Use one-time virtual cards with exact amounts
* Set strict spending limits per card
* Always use HMAC signatures for embed requests
* Monitor card usage in the [Lithic Dashboard](https://app.lithic.com/)

### 📊 Reconciliation

* Store Lithic card tokens with invoice metadata
* Use metadata to associate cards with invoices
* Set up webhooks to track card lifecycle and usage
* Implement proper transaction matching for accounting

### 💰 Cost Optimization

* Monitor Lithic fees and pricing
* Optimize card creation timing
* Consider bulk operations for high-volume scenarios
* Set appropriate card expiration times