Lithic API Documentation | Cards

Cards

cards

Methods

List Cards -> CursorPage<

NonPCICard

get/v1/cards

List cards.

query Parameters

account_token: string

Optional

(format: uuid)

Returns cards associated with the specified account.

begin: string

Optional

(format: date-time)

Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time zone.

end: string

Optional

(format: date-time)

Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC time zone.

ending_before: string

Optional

A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.

memo: string

Optional

Returns cards containing the specified partial or full memo text.

page_size: number

Optional

(maximum: 100, minimum: 1, default: 50)

Page size (for pagination).

starting_after: string

Optional

A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.

state:

Optional

Returns cards with the specified state.

"CLOSED"

"OPEN"

"PAUSED"

"PENDING_ACTIVATION"

"PENDING_FULFILLMENT"

Response fields

data: Array<

NonPCICard

has_more: boolean

More data exists.

Request example

curl https://api.lithic.com/v1/cards \
    -H "Authorization: $LITHIC_API_KEY"

200Example

{
  "data": [
    {
      "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
      "account_token": "f3f4918c-dee9-464d-a819-4aa42901d624",
      "card_program_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
      "created": "2021-06-28T22:53:15Z",
      "funding": {
        "token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "created": "2019-12-27T18:11:19.117Z",
        "last_four": "xxxx",
        "state": "DELETED",
        "type": "DEPOSITORY_CHECKING",
        "account_name": "account_name",
        "nickname": "x"
      },
      "last_four": "xxxx",
      "pin_status": "OK",
      "spend_limit": 1000,
      "spend_limit_duration": "ANNUALLY",
      "state": "CLOSED",
      "type": "MERCHANT_LOCKED",
      "auth_rule_tokens": [
        "string"
      ],
      "bulk_order_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
      "cardholder_currency": "USD",
      "comment": "comment",
      "digital_card_art_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
      "exp_month": "06",
      "exp_year": "2027",
      "hostname": "hostname",
      "memo": "New Card",
      "network_program_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
      "pending_commands": [
        "string"
      ],
      "product_id": "1",
      "replacement_for": "5e9483eb-8103-4e16-9794-2106111b2eca",
      "substatus": "LOST"
    }
  ],
  "has_more": true
}

Create Card ->

Card

post/v1/cards

Create a new virtual or physical card. Parameters shipping_address and product_id only apply to physical cards.

Get Card ->

Card

get/v1/cards/{card_token}

Get card configuration such as spend limit and state.

Update Card ->

Card

patch/v1/cards/{card_token}

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

Note: setting a card to a CLOSED state is a final action that cannot be undone.

Provision Card Digital Wallet -> { provisioning_payload }

post/v1/cards/{card_token}/provision

Allow your cardholders to directly add payment cards to the device's digital wallet (e.g. Apple Pay) with one touch from your app.

This requires some additional setup and configuration. Please Contact Us or your Customer Success representative for more information.

Reissue Physical Card ->

Card

post/v1/cards/{card_token}/reissue

Initiate print and shipment of a duplicate physical card (e.g. card is physically damaged). The PAN, expiry, and CVC2 will remain the same and the original card can continue to be used until the new card is activated. Only applies to cards of type PHYSICAL. A card can be reissued or renewed a total of 8 times.

Embedded Card Ui -> string

get/v1/embed/card

Handling full card PANs and CVV codes requires that you comply with the Payment Card Industry Data Security Standards (PCI DSS). Some clients choose to reduce their compliance obligations by leveraging our embedded card UI solution documented below.

In this setup, PANs and CVV codes are presented to the end-user via a card UI that we provide, optionally styled in the customer's branding using a specified css stylesheet. A user's browser makes the request directly to api.lithic.com, so card PANs and CVVs never touch the API customer's servers while full card data is displayed to their end-users. The response contains an HTML document (see Embedded Card UI or Changelog for upcoming changes in January). This means that the url for the request can be inserted straight into the src attribute of an iframe.

<iframe id="card-iframe"
        src="https://sandbox.lithic.com/v1/embed/card?embed_request=eyJjc3MiO...;hmac=r8tx1..."
        allow="clipboard-write" class="content"></iframe>

You should compute the request payload on the server side. You can render it (or the whole iframe) on the server or make an ajax call from your front end code, but do not ever embed your API key into front end code, as doing so introduces a serious security vulnerability.

Get Card S Available Spend Limit ->

CardSpendLimits

get/v1/cards/{card_token}/spend_limits

Get a Card's available spend limit, which is based on the spend limit configured on the Card and the amount already spent over the spend limit's duration. For example, if the Card has a monthly spend limit of $1000 configured, and has spent $600 in the last month, the available spend limit returned would be $400.

Renew A Card ->

Card

post/v1/cards/{card_token}/renew

Applies to card types PHYSICAL and VIRTUAL. For PHYSICAL, creates a new card with the same card token and PAN, but updated expiry and CVC2 code. The original card will keep working for card-present transactions until the new card is activated. For card-not-present transactions, the original card details (expiry, CVC2) will also keep working until the new card is activated. A PHYSICAL card can be reissued or renewed a total of 8 times. For VIRTUAL, the card will retain the same card token and PAN and receive an updated expiry and CVC2 code. product_id, shipping_method, shipping_address, carrier are only relevant for renewing PHYSICAL cards.

Search For Card By Pan ->

Card

post/v1/cards/search_by_pan

Get card configuration such as spend limit and state. Customers must be PCI compliant to use this endpoint. Please contact [email protected] for questions. Note: this is a POST endpoint because it is more secure to send sensitive data in a request body than in a URL.

Convert Virtual To Physical Card ->

Card

post/v1/cards/{card_token}/convert_physical

Convert a virtual card into a physical card and manufacture it. Customer must supply relevant fields for physical card creation including product_id, carrier, shipping_method, and shipping_address. The card token will be unchanged. The card's type will be altered to PHYSICAL. The card will be set to state PENDING_FULFILLMENT and fulfilled at next fulfillment cycle. Virtual cards created on card programs which do not support physical cards cannot be converted. The card program cannot be changed as part of the conversion. Cards must be in an OPEN state to be converted. Only applies to cards of type VIRTUAL (or existing cards with deprecated types of DIGITAL_WALLET and UNLOCKED).

Web Push Provision Card Digital Wallet -> { jws, state } | { google_opc, tsp_opc }

post/v1/cards/{card_token}/web_provision

Allow your cardholders to directly add payment cards to the device's digital wallet from a browser on the web. Currently only suported for Apple Pay.

This requires some additional setup and configuration. Please Contact Us or your Customer Success representative for more information.

Domain types

Card =

NonPCICard

Card details with potentially PCI sensitive information for Enterprise customers

CardSpendLimits = { available_spend_limit, spend_limit, spend_velocity }

NonPCICard = { token, account_token, card_program_token, 22 more... }

Card details without PCI information

ProvisionResponse = { activationData, encryptedData, ephemeralPublicKey }

Object containing the fields required to add a card to Apple Pay. Applies only to Apple Pay wallet.

SpendLimitDuration = "ANNUALLY" | "FOREVER" | "MONTHLY" | 1 more...

Spend limit duration values:

ANNUALLY - Card will authorize transactions up to spend limit for the trailing year.
FOREVER - Card will authorize only up to spend limit for the entire lifetime of the card.
MONTHLY - Card will authorize transactions up to spend limit for the trailing month. To support recurring monthly payments, which can occur on different day every month, the time window we consider for monthly velocity starts 6 days after the current calendar date one month prior.
TRANSACTION - Card will authorize multiple transactions if each individual transaction is under the spend limit.

Cards