HomeProcess Card Payments

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
  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:

1const virtualCard = await lithic.cards.create({
2  type: 'VIRTUAL',
3  program_id: cardProgram.token,
4  spend_controls: {
5    spend_limit: invoice.amount * 100, // Amount in cents
6    spend_limit_duration: 'TRANSACTION'
7  },
8  state: 'ACTIVE',
9  metadata: {
10    invoice_id: invoice.id,
11    vendor_id: invoice.vendor_id
12  }
13});

This is just an example, please refer to the Lithic documentation 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:

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:

1{
2  "type": "html",
3  "html": "<html><body><h1>Invoice Details</h1><a href=\"https://www.payment-gateway.com/invoice/123123\">Pay Invoice</a></body></html>",
4  "cardDetails": {
5    "type": "lithic",
6    "firstName": "John",
7    "lastName": "Doe",
8    "postalCode": "12345",
9    "country": "US",
10    "cardType": "credit",
11    "embedRequest": "eyJ0b2tlbiI6ImQ2ODkxZGI2LThlNzgtNGYxYS1iMTUyLTk5OTc3N2VjM2Q4MiIsImNzcyI6Imh0dHBzOi8vc3RvcmFnZS5nb29nbGVhcGlzLmNvbS9tZXJjb2EtcGFydG5lci1sb2dvcy9saXRoaWMuY3NzIn0=",
12    "hmac": "lEmiyyZnWuOpx8qO3g9cDGeRj7L30/SbRdvowxyCmfg="
13  }
14}

Field Descriptions

Card Details Object

FieldTypeRequiredDescription
typestringYesMust be "lithic"
firstNamestringYesCardholder’s first name
lastNamestringYesCardholder’s last name
postalCodestringYesBilling address postal code
countrystringYesBilling address country (ISO code)
cardTypestringNoCard type ("credit" or "debit")
embedRequeststringYesBase64-encoded embed request JSON
hmacstringYesHMAC-SHA256 signature of the embed request

Embed Request and HMAC Signature Generation

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

1const embedRequestObj = {
2  token: "d6891db6-8e78-4f1a-b152-999777ec3d82", // Your Lithic card token
3  css: "https://storage.googleapis.com/mercoa-partner-logos/lithic.css", // Optional styling
4  expiration: "2024-12-31T23:59:59Z", // Optional expiration time
5  target_origin: "https://yourdomain.com" // Optional target origin for iframe communication
6};
7
8const embedRequest = Buffer.from(JSON.stringify(embedRequestObj)).toString('base64');

Generate the HMAC signature using your Lithic API key:

1const crypto = require('crypto');
2
3const hmac = crypto
4  .createHmac('sha256', process.env.LITHIC_API_KEY)
5  .update(JSON.stringify(embedRequestObj))
6  .digest('base64');

This is just an example, please refer to the Lithic documentation 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

📊 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