Card Schema

{
  "created": String,
  "cvv": String,
  "funding": Object,
  "exp_month": String,
  "exp_year": String,
  "hostname": String,
  "last_four": String,
  "memo": String,
  "pan": String,
  "spend_limit": Integer,
  "spend_limit_duration": String,
  "state": String,
  "token": String,
  "type": String,
  "auth_rule_tokens": List
}

Note that due to PCI compliance requirements, the pan, cvv, exp_month, and exp_year fields are only available for customers who have verified PCI compliance. All customers will see these fields in Sandbox.

Create Card

API Reference: Create card

Create either a virtual or physical card.

🚧

Before physical cards can be issued, there are a few onboarding steps with external party dependencies that must be completed. Please Contact Us or your Customer Success rep for more information. Steps required include:

1. Establish and validate new BINs with the network and card manufacturer; this ensures that BINs are set up correctly and are ready for use, that transactional data will be sent securely, and that physical cards can be issued by the manufacturer
2. Set up requirements for card manufacturing (e.g., card art)
3. Test and confirm card configurations (e.g., spend testing, shipping) for final approval

POST https://api.lithic.com/v1/cards

Sample Request

curl https://api.lithic.com/v1/cards \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "type": "SINGLE_USE",
     "memo": "New Card",
     "spend_limit": 1000,
     "spend_limit_duration": "TRANSACTION",
     "state": "OPEN"
}
'

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 1000,
  "spend_limit_duration": "TRANSACTION",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "auth_rule_tokens": [
     "6397a416-bac6-464c-9647-b006f3a5f91d"
  ],
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}

Shipping Address Schema

Only applies to cards of type PHYSICAL.

Upon creation of a physical card, the card details can immediately be provided to the cardholder to be used virtually until they receive the physical card. The reverse (creating a virtual card, then later provisioning a physical version with the same card details) is not possible.

Update Card

API Reference: Update card

Update the specified properties of the card. Unsupplied properties will remain unchanged.

PATCH https://api.lithic.com/v1/cards/{card_token}

Sample Request

curl https://api.lithic.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "memo": "New Card",
     "spend_limit": 2000,
     "spend_limit_duration": "FOREVER"
}
'

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 2000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "auth_rule_tokens": [
     "6397a416-bac6-464c-9647-b006f3a5f91d"
  ],
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}

List Cards

API Reference: List cards

Get details for all cards or a specified card. This endpoint can only be used for cards that are managed by the program associated with the calling API key. If card_token is passed in as a path parameter, the endpoint returns a single object representing the card specified. Otherwise, a list of objects is returned.

GET https://api.lithic.com/v1/cards/{card_token}

Sample Request

curl https://api.lithic.com/v1/cards/7ef7d65c-9023-4da3-b113-3b8583fd7951 \
  -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 2000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "auth_rule_tokens": [
     "6397a416-bac6-464c-9647-b006f3a5f91d"
  ],
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}

Reissue Card (Enterprise)

API Reference: Reissue card

Initiate print and shipment of a duplicate physical card (e.g., card is expiring, card is physically damaged, etc.) If the original card is still active, it will remain active until the new card has been received and activated.

POST https://api.lithic.com/v1/cards/{card_token}/reissue

Sample Request

curl https://api.lithic.com/v1/card/7ef7d65c-9023-4da3-b113-3b8583fd7951/reissue \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \

Sample Response

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "SINGLE_USE",
  "spend_limit": 2000,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "funding": {
    "created": "2020-07-08 17:57:36",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING",
    "state": "ENABLED",
    "nickname": "",
    "account_name": "New Account",
    "last_four": "5263",
  },
  "auth_rule_tokens": [
     "6397a416-bac6-464c-9647-b006f3a5f91d"
  ],
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027",
}

Encrypted PIN Block (Enterprise)

Cardholder PINs can be configured for cards of type PHYSICAL and VIRTUAL. The create card and update card endpoints can set and update the cardholder PIN.

🚧

Due to the sensitive nature, PINs must be encrypted on the frontend immediately after user input.

An Encrypted PIN block is a JSON blob, encrypted with the Lithic API public key, base64 digest.

api.lithic.com.pub.pem

{
  "nonce": Integer,
  "pin": String
}

Examples

import base64
import json
import random

# pip install pycryptodome
from Crypto.Cipher    import PKCS1_OAEP
from Crypto.PublicKey import RSA

pin_block =  {
    "nonce": random.randint(1e8, 1e12),
    "pin": "1234"
}

with open("path/to/api.lithic.com.pub.pem") as f:
    cipher = PKCS1_OAEP.new(RSA.importKey(f.read()))

ciphertext = cipher.encrypt(json.dumps(pin_block).encode('utf-8'))

# Use this for the "pin" field value when creating or updating cards
encrypted_pin_block = base64.b64encode(ciphertext)

const fs = require("fs");

// npm install node-forge
const forge = require("node-forge");

const pem = fs.readFileSync("path/to/api.lithic.com.pub.pem", "utf8");
const publicKey = forge.pki.publicKeyFromPem(pem);

function randomInt(low, high) {
  // Generate random integer between low and high, inclusive
  return Math.floor(Math.random() * (high - low + 1) + low)
}

const pinBlock =  {
  "nonce": randomInt(1e8, 1e12),
  "pin": "1234"
}

const ciphertext = publicKey.encrypt(JSON.stringify(pinBlock), "RSA-OAEP", {
  md: forge.md.sha1.create(),
  mgf1: {
    md: forge.md.sha1.create()
  }
});

// Use this for the "pin" field value when creating or updating cards
const encryptedPinBlock = forge.util.encode64(ciphertext);
console.log(encryptedPinBlock);

package main

import (
    crand "crypto/rand"
    "crypto/rsa"
    "crypto/sha1"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "encoding/pem"
    "fmt"
    "io/ioutil"
    rand "math/rand"
    "os"
    "time"
)

type PinBlock struct {
    Nonce int    `json:"nonce"`
    Pin   string `json:"pin"`
}

func checkError(err error) {
    if err != nil {
        fmt.Println("Fatal error ", err.Error())
        os.Exit(1)
    }
}

func loadKey(fileName string) (*rsa.PublicKey, error) {
    rawPem, err := ioutil.ReadFile(fileName)
    checkError(err)

    pemBlock, _ := pem.Decode(rawPem)

    return x509.ParsePKCS1PublicKey(pemBlock.Bytes)
}

func encrypt(msg []byte, publicKey *rsa.PublicKey) (string, error) {
    encryptedBytes, err := rsa.EncryptOAEP(
        sha1.New(),
        crand.Reader,
        publicKey,
        msg,
        nil,
    )
    if err != nil {
        return "", err
    }
    encodedData := base64.StdEncoding.EncodeToString(encryptedBytes)
    return encodedData, nil
}

func generateNonce() int {
    rand.Seed(time.Now().UnixNano())
    min := int(1e8)
    max := int(1e12)
    return min + rand.Intn(max-min+1)
}

func main() {
    pemFile := "path/to/api.lithic.com.pub.pem"

    publicKey, err := loadKey(pemFile)
    
    pinBlock := &PinBlock{Nonce: generateNonce(), Pin: "1234"}
    pinBlockBytes, err := json.Marshal(pinBlock)
    checkError(err)
    fmt.Println(string(pinBlockBytes))

    // Use this for the "pin" field value when creating or updating cards
    encoded, err := encrypt(pinBlockBytes, publicKey)
    checkError(err)

    fmt.Println(encoded)
}

extern crate openssl;

use base64;
use openssl::rsa::{Padding, Rsa};
use rand::Rng;
use serde::Serialize;
use serde_json;

#[derive(Serialize)]
struct PinBlock {
    pin: String,
    nonce: u128,
}

// This is the main function
fn main() {
    let mut rng = rand::thread_rng();

    let base: u128 = 10;
    let low: u128 = base.pow(8);
    let high: u128 = base.pow(12);
    let nonce = rng.gen_range(low..high);

    let pin = "1234";

    let pin_block = PinBlock {
        pin: pin.to_string(),
        nonce: nonce,
    };

    let data = serde_json::to_string(&pin_block).unwrap();

    // Encrypt with public key
    let public_key_pem = include_bytes!("path/to/api.lithic.com.pub.pem");

    let rsa = Rsa::public_key_from_pem_pkcs1(public_key_pem).expect("Error prasing public key");
    let mut buf: Vec<u8> = vec![0; rsa.size() as usize];
    let _ = rsa
        .public_encrypt(data.as_bytes(), &mut buf, Padding::PKCS1_OAEP)
        .unwrap();
    
    let encrypted_pin_block = base64::encode(&buf);

    println!("Encrypted PIN block: {:?}", encrypted_pin_block);
}

Enumerations

Card.type

Card.state

Card.spend_limit_duration