Cards
Learn how to create, update cards.
Card Details
Due to PCI compliance requirements, the
pan
andcvv
fields are only available in Production for customers who have verified PCI compliance.All customers will see these fields in Sandbox.
The following Card types are supported on the platform:
VIRTUAL
- The card will support card-not-present transactions and can be added to a digital wallet like Apple Pay or Google Pay (if the card program is digital wallet-enabled) to be used in stores. This will create a card that will not be manufactured, however aVIRTUAL
card can be changed to aPHYSICAL
card at later point in time through the Convert Virtual to Physical Card endpoint.PHYSICAL
- The card Manufactured and sent to the cardholder and can be used. The card will support card-not-present transactions, can be added to a digital wallet like Apple Pay or Google Pay (if the card program is digital wallet-enabled) and used in stores at POS. We offer white label branding, credit, ATM, PIN debit, chip/EMV, NFC and magstripe functionality. The program must be configured with aproduct_id
to supportPHYSICAL
cards.SINGLE_USE
- The card is closed upon first successful authorization and can only be used once. After the first transaction, additional purchases will be declined, but the card will remain available to process refunds. Note that merchants may still initiate force post charges (i.e., a clearing without a prior authorization) which Lithic is not able to decline. These may be subject to chargeback.
Cards can be in following 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. Upon creation of a physical card, the card details can immediately be provided to the cardholder to be used virtually until they receive the physical card. 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.
Create Card
API Reference: Create card
Create either a virtual or physical card.
Before physical cards can be issued, there are a few onboarding steps with external party dependencies that must be completed. Please Contact Us or your Customer Success rep for more information. Steps required include:
- 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
- Set up requirements for card manufacturing (e.g., card art)
- Test and confirm card configurations (e.g., spend testing, shipping) for final approval
List Cards
API Reference: List cards
Get details for all cards or a specified card. This endpoint can only be used for cards that are managed by the program associated with the calling API key.
Update Card
API Reference: Update card
Update the specified properties of the card. Unsupplied properties will remain unchanged.
Get Specific Card
API Reference: Get card
Get card configuration such as spend limit and state
Renew Physical Card
As physical cards approach expiry, customers can renew physical cards, generating a physical card with the same card token and PAN, but updated expiry and CVC2 code. API Reference: Renew Physical Card
This flow is best suited for replacing a card approaching expiry. To set up a card renewal flow:
- Make a POST request to
/cards/{card_token_UUID}/renew
. - This POST request will trigger a physical card shipment. As part of this POST request, you must specify an address for the card to be shipped.
- The card's state will change to
PENDING_FULFILLMENT
. Once the card has been created by the card manufacturer, the state will change again toÂPENDING_ACTIVATION
. Once the card is delivered to the cardholder, you should activate it by changing state toOPEN
. - The new physical card will only start working for card-present transactions once activated (the state is changed from
PENDING_ACTIVATION
back toOPEN
) - The original physical 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.
- Lithic will pass along the updated card details to Mastercard's Automatic Billing Updater. Participating merchants will be able to update the card-on-file information.
Replace Physical Card
Replace a card with a new physical card with a different PAN (e.g. card was stolen). API Reference: Replace Physical Card.
This flow closes the original card and creates a new card with a new PAN, expiry, CVC2, and card token. This is best suited for replacing a lost or stolen card whose number is no longer secure. To set up a card replacement flow:
- Make a POST request to the
/cards
endpoint. In your request, specify the UUID of the card you want to replace in thereplacement_for
field. - This POST request will trigger a physical card shipment. As part of this POST request, you must specify an address for the card to be shipped.
- Please note: this POST request will immediately change the predecessor physical card's state to
CLOSED
and that physical card will no longer be able to transact. - The new card's state will change to
PENDING_FULFILLMENT
. Once the card has been created by the card manufacturer, the state will change again toÂPENDING_ACTIVATION
. Once the card is delivered to the cardholder, you should activate it by changing state toOPEN
. - The replacement card will be created with the
replacement_for
field populated with the predecessor card'stoken
for future reference. - Lithic will pass along the updated card details to Mastercard's Automatic Billing Updater. Participating merchants will be able to update the card-on-file information.
Reissue Physical Card
Initiate print and shipment of a replacement physical card (e.g. card is physically damaged). API Reference: Reissue card.
Note: We recommend customers use the Renew Physical Card or Replace Physical Card endpoints if possible. Please reference the table below to understand the differences
Reissue Renew Replace Card token same same new PAN same same new Expiry same new new CVC2 same new new New card can transact once activated once activated once activated Old card can transact until new card is activated until new card is activated old card is closed immediately
When you reissue a physical card, the following will happen:
- The card state will change from
OPEN
toPENDING_FULFILLMENT
. Once the card has been created by the card manufacturer, the state will change again toPENDING_ACTIVATION
. Once the card is delivered to the cardholder, you should activate it by changing state toOPEN
. - The PAN, expiry, and CVC2 will remain the same (with the exception of cards created before 5/2023 - CVC2 will change in those cases). These credentials can be used for card-not-present transactions at any time.
- The new physical card will only start working for card-present transactions once activated (the state is changed from
PENDING_ACTIVATION
back toOPEN
) - The original physical card will keep working for card-present transactions until the new card is activated.
Encrypted PIN Block
Cardholder PINs can be configured for cards of type PHYSICAL
and VIRTUAL
. You can provide cardholder PIN when creating cards using the create card endpoint. The update card endpoint can be used to set or update it later.
Due to their 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. The Lithic API public key is: api.lithic.com.pub.pem
Physical Card Shipped Webhook
When your physical cards are shipped, Lithic will send a webhook to your registered Events webhook URL(s) subscribing to events of type card.shipped
with the below payload. Check with your customer success manager if your manufacturer supports this webhook.
Updated 4 days ago