Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
Card

Create card

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

post/v1/cards

Headers

Idempotency-Keystring uuid

Idempotency key for the request

Request body

account_tokenstring uuid

Globally unique identifier for the account that the card will be associated with. Required for programs enrolling users using the /account_holders endpoint. See Managing Your Program for more information.

card_program_tokenstring uuid

For card programs with more than one BIN range. This must be configured with Lithic before use. Identifies the card program/BIN range under which to create the card. If omitted, will utilize the program's default card_program_token. In Sandbox, use 00000000-0000-0000-1000-000000000000 and 00000000-0000-0000-2000-000000000000 to test creating cards on specific card programs.

bulk_order_tokenstring uuid

Globally unique identifier for an existing bulk order to associate this card with. When specified, the card will be added to the bulk order for batch shipment. Only applicable to cards of type PHYSICAL

digital_card_art_tokenstring uuid

Specifies the digital card art to be displayed in the user’s digital wallet after tokenization. This artwork must be approved by Mastercard and configured by Lithic to use. See Flexible Card Art Guide.

exp_monthstring

Two digit (MM) expiry month. If neither exp_month nor exp_year is provided, an expiration date five years in the future will be generated. Five years is the maximum expiration date.

exp_yearstring

Four digit (yyyy) expiry year. If neither exp_month nor exp_year is provided, an expiration date five years in the future will be generated. Five years is the maximum expiration date.

memostring

Friendly name to identify the card.

pinstring

Encrypted PIN block (in base64). Applies to cards of type PHYSICAL and VIRTUAL. See Encrypted PIN Block.

product_idstring

Only applicable to cards of type PHYSICAL. This must be configured with Lithic before use. Specifies the configuration (i.e., physical card art) that the card should be manufactured with.

replacement_forstring uuid

Globally unique identifier for the card that this card will replace. If the card type is PHYSICAL it will be replaced by a PHYSICAL card. If the card type is VIRTUAL it will be replaced by a VIRTUAL card.

replacement_substatus'LOST' | 'COMPROMISED' | 'DAMAGED' | 'END_USER_REQUEST' | 'ISSUER_REQUEST' | 'NOT_ACTIVE' | 'SUSPICIOUS_ACTIVITY' | 'INTERNAL_REVIEW' | 'EXPIRED' | 'UNDELIVERABLE' | 'OTHER'

Card state substatus values for the card that this card will replace:

  • LOST - The physical card is no longer in the cardholder's possession due to being lost or never received by the cardholder.
  • COMPROMISED - Card information has been exposed, potentially leading to unauthorized access. This may involve physical card theft, cloning, or online data breaches.
  • DAMAGED - The physical card is not functioning properly, such as having chip failures or a demagnetized magnetic stripe.
  • END_USER_REQUEST - The cardholder requested the closure of the card for reasons unrelated to fraud or damage, such as switching to a different product or closing the account.
  • ISSUER_REQUEST - The issuer closed the card for reasons unrelated to fraud or damage, such as account inactivity, product or policy changes, or technology upgrades.
  • NOT_ACTIVE - The card hasn’t had any transaction activity for a specified period, applicable to statuses like PAUSED or CLOSED.
  • SUSPICIOUS_ACTIVITY - The card has one or more suspicious transactions or activities that require review. This can involve prompting the cardholder to confirm legitimate use or report confirmed fraud.
  • INTERNAL_REVIEW - The card is temporarily paused pending further internal review.
  • EXPIRED - The card has expired and has been closed without being reissued.
  • UNDELIVERABLE - The card cannot be delivered to the cardholder and has been returned.
  • OTHER - The reason for the status does not fall into any of the above categories. A comment should be provided to specify the reason.
replacement_commentstring

Additional context or information related to the card that this card will replace.

replacement_account_tokenstring uuid

Restricted field limited to select use cases. Lithic will reach out directly if this field should be used. Globally unique identifier for the replacement card's account. If this field is specified, replacement_for must also be specified. If replacement_for is specified and this field is omitted, the replacement card's account will be inferred from the card being replaced.

shipping_method'2_DAY' | 'BULK' | 'EXPEDITED' | 'EXPRESS' | 'PRIORITY' | 'STANDARD' | 'STANDARD_WITH_TRACKING'

Shipping method for the card. Only applies to cards of type PHYSICAL. Use of options besides STANDARD require additional permissions.

  • STANDARD - USPS regular mail or similar international option, with no tracking
  • STANDARD_WITH_TRACKING - USPS regular mail or similar international option, with tracking
  • PRIORITY - USPS Priority, 1-3 day shipping, with tracking
  • EXPRESS - FedEx or UPS depending on card manufacturer, Express, 3-day shipping, with tracking
  • 2_DAY - FedEx or UPS depending on card manufacturer, 2-day shipping, with tracking
  • EXPEDITED - FedEx or UPS depending on card manufacturer, Standard Overnight or similar international option, with tracking
  • BULK - Card will be shipped as part of a bulk fulfillment order. The shipping method and timeline are inherited from the parent bulk order.
spend_limitinteger

Amount (in cents) to limit approved authorizations (e.g. 100000 would be a $1,000 limit). Transaction requests above the spend limit will be declined. Note that a spend limit of 0 is effectively no limit, and should only be used to reset or remove a prior limit. Only a limit of 1 or above will result in declined transactions due to checks against the card limit.

spend_limit_duration'ANNUALLY' | 'FOREVER' | 'MONTHLY' | 'TRANSACTION'

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.
state'OPEN' | 'PAUSED'

Card state values:

  • OPEN - Card will approve authorizations (if they match card and account parameters).
  • PAUSED - Card will decline authorizations, but can be resumed at a later time.
type'MERCHANT_LOCKED' | 'PHYSICAL' | 'SINGLE_USE' | 'VIRTUAL' | 'UNLOCKED' | 'DIGITAL_WALLET' required

Card types:

  • VIRTUAL - Card will authorize at any merchant and can be added to a digital wallet like Apple Pay or Google Pay (if the card program is digital wallet-enabled).
  • PHYSICAL - Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. Reach out at lithic.com/contact for more information.
  • SINGLE_USE - Card is closed upon first successful authorization.
  • MERCHANT_LOCKED - Card is locked to the first merchant that successfully authorizes the card.
  • UNLOCKED - [Deprecated] Similar behavior to VIRTUAL cards, please use VIRTUAL instead.
  • DIGITAL_WALLET - [Deprecated] Similar behavior to VIRTUAL cards, please use VIRTUAL instead.

Example request

{
  "card_program_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
  "bulk_order_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
  "digital_card_art_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
  "exp_month": "06",
  "exp_year": "2027",
  "memo": "New Card",
  "product_id": "1",
  "replacement_for": "5e9483eb-8103-4e16-9794-2106111b2eca",
  "replacement_account_token": "5e9483eb-8103-4e16-9794-2106111b2eca",
  "shipping_address": {
    "address1": "5 Broad Street",
    "address2": "Unit 25A",
    "city": "NEW YORK",
    "country": "USA",
    "email": "johnny@appleseed.com",
    "first_name": "Michael",
    "last_name": "Bluth",
    "line2_text": "The Bluth Company",
    "phone_number": "+15555555555",
    "postal_code": "10001-1809",
    "state": "NY"
  }
}

Response

OK

account_tokenstring required

Globally unique identifier for the account to which the card belongs.

auth_rule_tokensstring[]

List of identifiers for the Auth Rule(s) that are applied on the card. This field is deprecated and will no longer be populated in the Card object. The key will be removed from the schema in a future release. Use the /auth_rules endpoints to fetch Auth Rule information instead.

card_program_tokenstring required

Globally unique identifier for the card program on which the card exists.

bulk_order_tokenstring uuid nullable

Globally unique identifier for the bulk order associated with this card. Only applicable to physical cards that are part of a bulk shipment

replacement_forstring nullable

If the card is a replacement for another card, the globally unique identifier for the card that was replaced.

cardholder_currencystring

3-character alphabetic ISO 4217 code for the currency of the cardholder.

createdstring date-time required

An RFC 3339 timestamp for when the card was created. UTC time zone.

digital_card_art_tokenstring nullable

Specifies the digital card art to be displayed in the user's digital wallet after tokenization. This artwork must be approved by Mastercard and configured by Lithic to use.

exp_monthstring

Two digit (MM) expiry month.

exp_yearstring

Four digit (yyyy) expiry year.

hostnamestring

Hostname of card's locked merchant (will be empty if not applicable).

last_fourstring required

Last four digits of the card number.

memostring

Friendly name to identify the card.

network_program_tokenstring nullable

Globally unique identifier for the card's network program. Null if the card is not associated with a network program. Currently applicable to Visa cards participating in Account Level Management only

pending_commandsstring[]

Indicates if there are offline PIN changes pending card interaction with an offline PIN terminal. Possible commands are: CHANGE_PIN, UNBLOCK_PIN. Applicable only to cards issued in markets supporting offline PINs.

pin_status'OK' | 'BLOCKED' | 'NOT_SET' required

Indicates if a card is blocked due a PIN status issue (e.g. excessive incorrect attempts).

product_idstring nullable

Only applicable to cards of type PHYSICAL. This must be configured with Lithic before use. Specifies the configuration (i.e., physical card art) that the card should be manufactured with.

spend_limitinteger required

Amount (in cents) to limit approved authorizations (e.g. 100000 would be a $1,000 limit). Transaction requests above the spend limit will be declined.

spend_limit_duration'ANNUALLY' | 'FOREVER' | 'MONTHLY' | 'TRANSACTION' required

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.
state'CLOSED' | 'OPEN' | 'PAUSED' | 'PENDING_ACTIVATION' | 'PENDING_FULFILLMENT' required

Card state values: * CLOSED - Card will no longer approve authorizations. Closing a card cannot be undone. * OPEN - Card will approve authorizations (if they match card and account parameters). * PAUSED - Card will decline authorizations, but can be resumed at a later time. * PENDING_FULFILLMENT - The 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_ACTIVATION - At regular intervals, 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 or can be added to mobile wallets. 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.

substatus'LOST' | 'COMPROMISED' | 'DAMAGED' | 'END_USER_REQUEST' | 'ISSUER_REQUEST' | 'NOT_ACTIVE' | 'SUSPICIOUS_ACTIVITY' | 'INTERNAL_REVIEW' | 'EXPIRED' | 'UNDELIVERABLE' | 'OTHER' nullable

Card state substatus values: * LOST - The physical card is no longer in the cardholder's possession due to being lost or never received by the cardholder. * COMPROMISED - Card information has been exposed, potentially leading to unauthorized access. This may involve physical card theft, cloning, or online data breaches. * DAMAGED - The physical card is not functioning properly, such as having chip failures or a demagnetized magnetic stripe. * END_USER_REQUEST - The cardholder requested the closure of the card for reasons unrelated to fraud or damage, such as switching to a different product or closing the account. * ISSUER_REQUEST - The issuer closed the card for reasons unrelated to fraud or damage, such as account inactivity, product or policy changes, or technology upgrades. * NOT_ACTIVE - The card hasn’t had any transaction activity for a specified period, applicable to statuses like PAUSED or CLOSED. * SUSPICIOUS_ACTIVITY - The card has one or more suspicious transactions or activities that require review. This can involve prompting the cardholder to confirm legitimate use or report confirmed fraud. * INTERNAL_REVIEW - The card is temporarily paused pending further internal review. * EXPIRED - The card has expired and has been closed without being reissued. * UNDELIVERABLE - The card cannot be delivered to the cardholder and has been returned. * OTHER - The reason for the status does not fall into any of the above categories. A comment can be provided to specify the reason.

commentstring

Additional context or information related to the card.

tokenstring required

Globally unique identifier.

type'MERCHANT_LOCKED' | 'PHYSICAL' | 'SINGLE_USE' | 'VIRTUAL' | 'UNLOCKED' | 'DIGITAL_WALLET' required

Card types: * VIRTUAL - Card will authorize at any merchant and can be added to a digital wallet like Apple Pay or Google Pay (if the card program is digital wallet-enabled). * PHYSICAL - Manufactured and sent to the cardholder. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. * SINGLE_USE - Card is closed upon first successful authorization. * MERCHANT_LOCKED - Card is locked to the first merchant that successfully authorizes the card. * UNLOCKED - [Deprecated] Similar behavior to VIRTUAL cards, please use VIRTUAL instead. * DIGITAL_WALLET - [Deprecated] Similar behavior to VIRTUAL cards, please use VIRTUAL instead.

panstring

Primary Account Number (PAN) (i.e. the card number). Customers must be PCI compliant to have PAN returned as a field in production. Please contact https://support.lithic.com/ for questions.

cvvstring

Three digit cvv printed on the back of the card.

Example response

{
  "pan": "4111111289144142",
  "cvv": "776"
}