Cards

Learn more about cards.

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
}
createdAn ISO 8601 timestamp for when the card was created
cvv (Enterprise) Three digit CVV printed on the back of the card
fundingSee Funding Schema
exp_month (Enterprise) Two digit (MM) expiry month
exp_year (Enterprise) Four digit (yyyy) expiry year
hostnameHostname of card’s locked merchant (will be empty if not applicable)
last_fourLast four digits of the card number
memoFriendly name to identify the card
pan (Enterprise) Sixteen digit card number
spend_limitAmount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined
spend_limit_durationTRANSACTION, MONTHLY, ANNUALLY, FOREVER
stateOPEN, PAUSED, CLOSED, PENDING_FULFILLMENT, PENDING_ACTIVATION
tokenGlobally unique identifier
typeSINGLE_USE, MERCHANT_LOCKED, UNLOCKED, PHYSICAL

Create Card (Issuing)

API reference: Create card

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"
}
memo (optional)Friendly name to identify the card
typeSINGLE_USE, MERCHANT_LOCKED, DIGITAL_WALLET, UNLOCKED, PHYSICAL (Unlocked & physical cards require additional privileges. All physical cards have digital wallet functionality and are unlocked.)
funding_token (optional)The token for the desired FundingAccount to use when making transactions with this card
pin (optional)Encrypted PIN block (in base64). Only applies on cards of type PHYSICAL. See Physical Cards.
spend_limit (optional)Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined
spend_limit_duration (optional)TRANSACTION, MONTHLY, ANNUALLY, FOREVER
state (optional)OPEN, PAUSED
shipping_address (optional)Shipping Address. Only applies on cards of type PHYSICAL
product_id (optional)Alphanumeric identifier to specify physical card manufacturing attributes. Only applies to cards of type PHYSICAL. This must be configured with Lithic before use.
card_program_token (optional)Token belonging to the card program under which to create the card. This must be configured with Lithic before use.
exp_month (optional)Two digit (MM) expiry month. If neither exp_month nor exp_year is provided, an expiration date will be generated.
exp_year (optional)Four digit (yyyy) expiry year. If neither exp_month nor exp_year is provided, an expiration date will be generated.
account_token (multi-account users only)Token identifying the account the card will be associated with. Only applicable if using account enrollment. See Managing Identities for more information.

Update Card (Issuing)

API reference: Update card

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

🚧

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"
}
card_tokenThe unique token of the card to update
state (optional)OPEN, PAUSED, CLOSED
funding_token (optional)The token for the desired FundingAccount to use when making transactions with this card
memo (optional)Friendly name to identify the card
pin (optional)Only applies on cards of type PHYSICAL. See Physical Cards.
spend_limit (optional)Amount (in cents) to limit approved authorizations. Transaction requests above the spend limit will be declined.
spend_limit_duration (optional)TRANSACTION, MONTHLY, ANNUALLY, FOREVER
account_token (multi-account users only)Token identifying the account which owns the card. Only applicable if using account enrollment. See Managing Identities for more information.

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
}
pageFor pagination. The default is 1.
page_sizeFor pagination. The default value page size is 50 and the maximum is 1,000.
beginDate string in the form YYYY-MM-DD, only cards created after the specified date will be included
endDate string in the form YYYY-MM-DD, only cards created before the specified date will be included
card_tokenReturns a specific card.
account_token (multi-account users only)Returns cards associated with this account. Only applicable if using account enrollment. See Managing Identities for more information.

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

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

Enumerations

Card.type

SINGLE_USECard will close shortly after the first transaction
MERCHANT_LOCKEDCard is locked to first merchant that successfully authorizes the card
UNLOCKED (Issuing) Card will authorize at any merchant. Creating these cards requires additional privileges
PHYSICAL (Enterprise) Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. Contact [email protected] for more information.
DIGITAL_WALLET (Enterprise) Cards that can be provisioned to a digital wallet like Google Pay or Apple Wallet.

Card.state

OPENCard will approve authorizations (if they match card and account parameters)
PAUSEDCard will decline authorizations but can be resumed at a later time
CLOSEDCard will no longer approve authorizations. Closing a card cannot be undone
PENDING_FULFILLMENTThe initial state for cards of type PHYSICAL. The card is provisioned pending manufacturing and fulfillment. Cards in this state can accept authorizations for e-commerce purchases, but not for "Card Present" purchases where the physical card itself is present.
PENDING_ACTIVATIONEach business day at 2pm Eastern Time Zone (ET), cards of type PHYSICAL in state PENDING_FULFILLMENT are sent to the card production warehouse and updated to state PENDING_ACTIVATION. Similar to PENDING_FULFILLMENT, cards in this state can be used for e-commerce transactions. API clients should update the card's state to OPEN only after the cardholder confirms receipt of the card.

In Sandbox, the same daily batch fulfillment occurs, but no cards are actually manufactured.

Card.spend_limit_duration

TRANSACTIONCard will authorize multiple transactions if each individual transaction is under the spend limit
MONTHLYCard will authorize transactions up to spend limit for the trailing month. (Note month is calculated as this calendar date one month prior)
ANNUALLYCard will authorize transactions up to spend limit in a calendar year
FOREVERCard will authorize only up to spend limit for the entire lifetime of the card

Did this page help you?