Card Schema

{
  "created": String,
  "cvv": String,
  "funding": FundingAccount,
  "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
}

Create Card

API reference: Create card

Creates either a virtual or physical card [beta]. Parameters pin, shipping_address, and product_id only apply to physical cards.

🚧

Before physical cards can be issued, there are a few onboarding steps with external party dependencies that must be completed. Reach out to [email protected] or your account 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/card

Sample Request

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

Sample Response

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

Update Card

API reference: Update card

Update the specified properties of the card. Unsupplied properties will remain unchanged. pin parameter only applies to physical cards [beta].

🚧

Setting a card to a CLOSED state is a final action that cannot be undone.

PUT https://api.lithic.com/v1/card

API reference: Update card

Sample Request

curl https://api.lithic.com/v1/card \
  -X PUT \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memo":"Sample Name","spend_limit":100,"spend_limit_duration":"FOREVER","state":"OPEN","card_token":"f5f905f5-8a8e-49bf-a9b4-c0adaa401456"}'

Sample Response

{
  "created": "2021-05-07T17:27:46Z",
  "cvv": "742",
  "exp_month": "05",
  "exp_year": "2027",
  "funding": {
    "account_name": "Sandbox",
    "created": "2020-07-08 17:57:36",
    "last_four": "5263",
    "nickname": "",
    "state": "ENABLED",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING"
  },
  "hostname": "",
  "last_four": "4938",
  "memo": "Sample Name",
  "pan": "4111111222794938",
  "spend_limit": 100,
  "spend_limit_duration": "FOREVER",
  "state": "OPEN",
  "token": "f5f905f5-8a8e-49bf-a9b4-c0adaa401456",
  "type": "SINGLE_USE"
}

List Cards

API reference: Get cards

GET https://api.lithic.com/v1/card

Sample Request

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

Sample Response

{
  "data": [
    {
      "created": "2021-05-07T17:27:46Z",
      "cvv": "742",
      "exp_month": "05",
      "exp_year": "2027",
      "funding": {
          "account_name": "Sandbox",
          "created": "2020-07-08 17:57:36",
          "last_four": "5263",
          "nickname": "",
          "state": "ENABLED",
          "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
          "type": "DEPOSITORY_CHECKING"
      },
      "hostname": "",
      "last_four": "4938",
      "memo": "Samplejka",
      "pan": "4111111222794938",
      "spend_limit": 100,
      "spend_limit_duration": "FOREVER",
      "state": "OPEN",
      "token": "f5f905f5-8a8e-49bf-a9b4-c0adaa401456",
      "type": "SINGLE_USE"
    },
  ],
  "page": 1,
  "total_entries": 1,
  "total_pages": 1
}

Any combination of the queries may be used together in the form:

[url]?[query field]=[query value]&[query field]=[query value]

Encrypted PIN Block (Enterprise)

Physical cards [beta] can be provisioned for ATM/PIN debit access which requires a cardholder PIN. 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)
}

Reissue Card (Enterprise)

API reference: Reissue Card

Initiate print and shipment of a duplicate card. Only applies to cards of type PHYSICAL [beta].

POST https://api.lithic.com/v1/card/reissue

Sample Request

curl https://api.lithic.com/v1/card/reissue \
  -X POST \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_token":"589e1412-b132-48ac-ab5c-befd02535a57"}'

Sample Response

{
  "created": "2021-06-28T22:58:36Z",
  "cvv": "162",
  "exp_month": "06",
  "exp_year": "2027",
  "funding": {
    "account_name": "Sandbox",
    "created": "2020-07-08 17:57:36",
    "last_four": "5263",
    "nickname": "",
    "state": "ENABLED",
    "token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
    "type": "DEPOSITORY_CHECKING"
  },
  "hostname": "",
  "last_four": "5205",
  "memo": "",
  "pan": "4111111540285205",
  "spend_limit": 0,
  "spend_limit_duration": "TRANSACTION",
  "state": "PENDING_FULFILLMENT",
  "token": "589e1412-b132-48ac-ab5c-befd02535a57",
  "type": "PHYSICAL"
}

Enumerations

Card.type

Card.state

Card.spend_limit_duration