Lithic Card API
The Card API from Lithic — 16 operation(s) for card.
OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@lithic.com
description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.
Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.
'
termsOfService: https://lithic.com/legal/terms
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.txt
title: Lithic Developer 3DS Card API
version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Card
paths:
/v1/cards/{card_token}/signals:
get:
operationId: getCardSignals
summary: Fetch card signals
description: 'Returns behavioral feature state derived from a card''s transaction history.
These signals expose the same data used by behavioral rule attributes (e.g. `AMOUNT_Z_SCORE` with `scope: CARD`, `IS_NEW_COUNTRY` with `scope: CARD`) and custom code `TRANSACTION_HISTORY_SIGNALS` features, allowing clients to inspect feature values before writing rules and debug rule behavior.
'
tags:
- Card
parameters:
- name: card_token
in: path
required: true
schema:
type: string
format: uuid
description: The token of the card to fetch signals for.
responses:
'200':
description: Card Signals
content:
application/json:
schema:
$ref: '#/components/schemas/signals-response'
'400':
$ref: '#/components/responses/components-responses-BadRequest'
'403':
$ref: '#/components/responses/responses-Forbidden'
'404':
$ref: '#/components/responses/components-responses-NotFound'
/v1/card_programs:
get:
description: List card programs.
operationId: getCardPrograms
parameters:
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/startingAfter'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/CardProgram'
type: array
has_more:
description: More data exists.
type: boolean
required:
- data
- has_more
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: List card programs
tags:
- Card
/v1/card_programs/{card_program_token}:
get:
description: Get card program.
operationId: getCardProgram
parameters:
- $ref: '#/components/parameters/cardProgramTokenPath'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CardProgram'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get card program
tags:
- Card
/v1/cards:
get:
description: List cards.
operationId: getCards
parameters:
- description: 'Returns cards associated with the specified account.
'
in: query
name: account_token
schema:
format: uuid
type: string
- description: 'Returns cards with the specified state.
'
in: query
name: state
schema:
enum:
- CLOSED
- OPEN
- PAUSED
- PENDING_ACTIVATION
- PENDING_FULFILLMENT
type: string
- description: 'Returns cards containing the specified partial or full memo text.
'
in: query
name: memo
schema:
type: string
- $ref: '#/components/parameters/beginTime'
- $ref: '#/components/parameters/endTime'
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/startingAfter'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/non_pci_card_response'
type: array
has_more:
description: More data exists.
type: boolean
required:
- data
- has_more
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: List cards
tags:
- Card
post:
description: 'Create a new virtual or physical card. Parameters `shipping_address` and `product_id` only apply to physical cards.
'
operationId: postCards
parameters:
- $ref: '#/components/parameters/idempotencyKey'
requestBody:
content:
application/json:
examples:
createCard:
summary: Create card
value:
memo: New Card
spend_limit: 1000
spend_limit_duration: TRANSACTION
state: OPEN
type: VIRTUAL
createPhysicalCard:
summary: Create a physical card
value:
carrier:
qr_code_url: https://lithic.com/activate-card/1
memo: New physical card
product_id: '783991122'
shipping_address:
address1: '123'
city: NEW YORK
country: USA
first_name: Johnny
last_name: Appleseed
postal_code: '10001'
state: NY
state: OPEN
type: PHYSICAL
schema:
properties:
account_token:
description: 'Globally unique identifier for the account that the card will be associated with. Required for programs enrolling users using the [/account\_holders endpoint](https://docs.lithic.com/docs/account-holders-kyc). See [Managing Your Program](doc:managing-your-program) for more information.
'
format: uuid
type: string
card_program_token:
description: 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.
example: 5e9483eb-8103-4e16-9794-2106111b2eca
format: uuid
type: string
bulk_order_token:
description: 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
example: 5e9483eb-8103-4e16-9794-2106111b2eca
format: uuid
type: string
carrier:
$ref: '#/components/schemas/Carrier'
digital_card_art_token:
description: 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](https://docs.lithic.com/docs/about-digital-wallets#flexible-card-art).
example: 5e9483eb-8103-4e16-9794-2106111b2eca
format: uuid
type: string
exp_month:
description: 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.
example: '06'
maxLength: 2
minLength: 2
type: string
exp_year:
description: 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.
example: '2027'
maxLength: 4
minLength: 4
type: string
memo:
description: Friendly name to identify the card.
example: New Card
type: string
pin:
description: Encrypted PIN block (in base64). Applies to cards of type `PHYSICAL` and `VIRTUAL`. See [Encrypted PIN Block](https://docs.lithic.com/docs/cards#encrypted-pin-block).
type: string
product_id:
description: 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.
example: '1'
type: string
replacement_for:
description: 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.
example: 5e9483eb-8103-4e16-9794-2106111b2eca
format: uuid
type: string
replacement_substatus:
description: '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.
'
enum:
- LOST
- COMPROMISED
- DAMAGED
- END_USER_REQUEST
- ISSUER_REQUEST
- NOT_ACTIVE
- SUSPICIOUS_ACTIVITY
- INTERNAL_REVIEW
- EXPIRED
- UNDELIVERABLE
- OTHER
type: string
replacement_comment:
description: Additional context or information related to the card that this card will replace.
type: string
replacement_account_token:
description: 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.
example: 5e9483eb-8103-4e16-9794-2106111b2eca
format: uuid
type: string
shipping_address:
$ref: '#/components/schemas/ShippingAddress'
shipping_method:
description: '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.
'
enum:
- 2_DAY
- BULK
- EXPEDITED
- EXPRESS
- PRIORITY
- STANDARD
- STANDARD_WITH_TRACKING
type: string
spend_limit:
description: 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.
example: 0
minimum: 0
type: integer
spend_limit_duration:
$ref: '#/components/schemas/spend_limit_duration'
state:
description: '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.
'
enum:
- OPEN
- PAUSED
type: string
type:
default: VIRTUAL
description: '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](https://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.
'
enum:
- MERCHANT_LOCKED
- PHYSICAL
- SINGLE_USE
- VIRTUAL
- UNLOCKED
- DIGITAL_WALLET
type: string
required:
- type
type: object
required: true
responses:
'200':
content:
application/json:
example:
account_token: f3f4918c-dee9-464d-a819-4aa42901d624
card_program_token: 5e9483eb-8103-4e16-9794-2106111b2eca
cardholder_currency: USD
created: '2021-06-28T22:53:15Z'
cvv: '776'
exp_month: '06'
exp_year: '2027'
funding:
account_name: Sandbox
created: '2020-07-08T17:57:36Z'
last_four: '5263'
nickname: checking account
state: ENABLED
token: b0f0d91a-3697-46d8-85f3-20f0a585cbea
type: DEPOSITORY_CHECKING
hostname: ''
last_four: '4142'
memo: New Card
pan: '4111111289144142'
replacement_for: null
spend_limit: 1000
spend_limit_duration: TRANSACTION
state: OPEN
token: 7ef7d65c-9023-4da3-b113-3b8583fd7951
type: VIRTUAL
pin_status: NOT_SET
schema:
$ref: '#/components/schemas/pci_card_response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Create card
tags:
- Card
/v1/cards/search_by_pan:
post:
description: 'Get card configuration such as spend limit and state. Customers must be PCI compliant to use this endpoint. Please contact [support@lithic.com](mailto:support@lithic.com) 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.*'
operationId: searchCardByPan
requestBody:
content:
application/json:
examples:
searchCardByPan:
summary: Search for card for by PAN.
value:
pan: '4111111289144142'
schema:
properties:
pan:
description: The PAN for the card being retrieved.
example: '4111111289144142'
type: string
required:
- pan
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pci_card_response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Search for card by PAN
tags:
- Card
/v1/cards/{card_token}:
get:
description: Get card configuration such as spend limit and state.
operationId: getCardByToken
parameters:
- $ref: '#/components/parameters/cardToken'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/pci_card_response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get card
tags:
- Card
patch:
description: '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.*
'
operationId: patchCardByToken
parameters:
- $ref: '#/components/parameters/cardToken'
requestBody:
content:
application/json:
examples:
updateCard:
summary: Update card
value:
memo: Updated Name
spend_limit: 100
spend_limit_duration: FOREVER
state: OPEN
schema:
properties:
digital_card_art_token:
description: 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](https://docs.lithic.com/docs/about-digital-wallets#flexible-card-art).
example: 00000000-0000-0000-1000-000000000000
format: uuid
type: string
memo:
description: Friendly name to identify the card.
example: New Card
type: string
network_program_token:
description: Globally unique identifier for the card's network program. Currently applicable to Visa cards participating in Account Level Management only.
example: 00000000-0000-0000-1000-000000000000
format: uuid
type: string
pin:
description: Encrypted PIN block (in base64). Only applies to cards of type `PHYSICAL` and `VIRTUAL`. Changing PIN also resets PIN status to `OK`. See [Encrypted PIN Block](https://docs.lithic.com/docs/cards#encrypted-pin-block).
type: string
pin_status:
description: Indicates if a card is blocked due a PIN status issue (e.g. excessive incorrect attempts). Can only be set to `OK` to unblock a card.
enum:
- OK
type: string
spend_limit:
description: 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.
example: 0
type: integer
spend_limit_duration:
$ref: '#/components/schemas/spend_limit_duration'
state:
description: '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.
'
enum:
- CLOSED
- OPEN
- PAUSED
type: string
substatus:
description: '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 should be provided to specify the reason.
'
enum:
- LOST
- COMPROMISED
- DAMAGED
- END_USER_REQUEST
- ISSUER_REQUEST
- NOT_ACTIVE
- SUSPICIOUS_ACTIVITY
- INTERNAL_REVIEW
- EXPIRED
- UNDELIVERABLE
- OTHER
type: string
comment:
description: Additional context or information related to the card.
type: string
type: object
required: true
responses:
'200':
content:
application/json:
example:
account_token: f3f4918c-dee9-464d-a819-4aa42901d624
card_program_token: 5e9483eb-8103-4e16-9794-2106111b2eca
cardholder_currency: USD
created: '2021-06-28T22:53:15Z'
cvv: '742'
exp_month: '05'
exp_year: '2027'
funding:
account_name: Sandbox
created: '2022-03-08T08:00:00Z'
last_four: '5263'
nickname: checking account
state: ENABLED
token: b0f0d91a-3697-46d8-85f3-20f0a585cbea
type: DEPOSITORY_CHECKING
hostname: ''
last_four: '4938'
memo: Updated Name
pan: '4111111289144142'
spend_limit: 100
spend_limit_duration: FOREVER
replacement_for: null
state: OPEN
token: f5f905f5-8a8e-49bf-a9b4-c0adaa401456
type: VIRTUAL
pin_status: NOT_SET
schema:
$ref: '#/components/schemas/pci_card_response'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Update card
tags:
- Card
/v1/cards/{card_token}/balances:
get:
description: Get the balances for a given card.
operationId: getCardBalance
parameters:
- description: UTC date of the balance to retrieve. Defaults to latest available balance
in: query
name: balance_date
schema:
format: date-time
type: string
- description: 'Balance after a given financial event occured.
For example, passing the event_token of a $5 CARD_CLEARING financial event will return a balance decreased by $5
'
in: query
name: last_transaction_event_token
schema:
format: uuid
type: string
- $ref: '#/components/parameters/cardToken'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/financial-account-balance'
type: array
has_more:
description: More data exists.
type: boolean
required:
- data
- has_more
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
summary: Get card balances
tags:
- Card
/v1/cards/{card_token}/financial_transactions:
get:
description: List the financial transactions for a given card.
operationId: getCardFinancialTransactions
parameters:
- description: Financial Transaction category to be returned.
in: query
name: category
schema:
enum:
- CARD
- TRANSFER
type: string
- description: Financial Transaction result to be returned.
in: query
name: result
schema:
enum:
- APPROVED
- DECLINED
type: string
- description: Financial Transaction status to be returned.
in: query
name: status
schema:
enum:
- DECLINED
- EXPIRED
- PENDING
- RETURNED
- SETTLED
- VOIDED
type: string
- $ref: '#/components/parameters/beginTime'
- $ref: '#/components/parameters/cardToken'
- $ref: '#/components/parameters/endTime'
- $ref: '#/components/parameters/endingBefore'
- $ref: '#/components/parameters/startingAfter'
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/financial-account-transaction'
type: array
has_more:
description: More data exists.
type: boolean
required:
- data
- has_more
type: object
description: OK
'400':
$ref: '#/components/
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lithic/refs/heads/main/openapi/lithic-card-api-openapi.yml