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:

1. Make a POST request to /cards/{card_token_UUID}/renew.
2. 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.
3. 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 to OPEN.
4. The new physical card will only start working for card-present transactions once activated (the state is changed from PENDING_ACTIVATION back to OPEN)
5. 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.
6. 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:

1. Make a POST request to the /cards endpoint. In your request, specify the UUID of the card you want to replace in the replacement_for field.
2. 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.
3. 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.
4. 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 to OPEN.
5. The replacement card will be created with the replacement_for field populated with the predecessor card's token for future reference.
6. 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). A card can be reissued a maximum of 8 times. 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:

1. The card state will change from OPEN 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 to OPEN.
2. 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.
3. The new physical card will only start working for card-present transactions once activated (the state is changed from PENDING_ACTIVATION back to OPEN)
4. The original physical card will keep working for card-present transactions until the new card is activated.

Convert virtual to physical cards

Convert a card from a VIRTUAL card to a PHYSICAL card and manufacture it.

Customer must supply relevant fields for physical card creation including product_id, carrier 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 the 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 a state of OPEN.

Only applies to cards of type VIRTUAL (existing cards with deprecated types of DIGITAL_WALLET or UNLOCKEDwill also be supported).

Unblock card PIN

As a security feature of Lithic-issued cards, the entry of 3 consecutive incorrect PIN attempts will result in the card's PIN becoming blocked. PIN blocking will only occur for cards whose PINs have been fully configured (set), and only when incorrect attempts are consecutive. Once a card PIN becomes blocked, the card will be unable to make subsequent PIN transactions until either:

1. The PIN is changed
2. The card program sends a PIN unblock request

Transactions which are declined due to a blocked PIN are treated similarly to other security-related declines, meaning that they occur prior to an ASA request being dispatched to the card program. Because of this, the first step to unblocking a card PIN is identifying when a card's PIN becomes blocked.

Identifying a blocked PIN

Lithic performs a series of basic checks on incoming authorizations to pre-decline invalid transactions before forwarding the authorization request to the card program via ASA for decisioning. These basic checks include things like verifying that the PAN is valid, that the card isn’t expired, and that the PIN input by the cardholder matches the PIN on file. This security-related, pre-ASA decline behavior extends to cards with blocked PINs.

Although the card program will not receive an ASA request, the card program will still be notified of the attempted transaction. This notification will come in the form of a card_transaction.updated webhook.

When a card’s PIN becomes blocked, the card program is encouraged to notify the cardholder to either reset/unblock their PIN or report the card as lost or stolen if unauthorized attempts were made. To know when a card’s PIN status has transitioned to blocked, this information is available via the authorization detailed result value of PIN_BLOCKED, available in the card_transaction.updated webhook.

See below an abridged card_transaction.updated webhook event showing an authorization that was declined due to a blocked PIN. To see the full structure of a transaction event, see the API reference here.

{
...
  "events": [
    {
      "amount": 12345,
      "created": "2024-06-19T21:09:45Z",
      "detailed_results": [
        "PIN_BLOCKED"
      ],
      "result": "INCORRECT_PIN",
      "token": "a9cf0fae-c782-4875-a0d7-a3c6a170541b",
      "type": "AUTHORIZATION"
    }
  ],
  ...
  },
  "result": "INCORRECT_PIN",
  ...
  }
}

Unblocking a PIN

Once a card’s PIN is blocked, there are two options to resolve it:

1. Send a PIN unblock request
2. Change the card's PIN

Card Unblock Request

To unblock a card's PIN, card programs can take advantage of the pin_status field included in the Lithic Update Card endpoint.

To unblock a card with a pin_status of BLOCKED without changing the PIN, send a PATCH request to the /cards endpoint updating the pin_status to OK.

Example Request

PATCH https://api.lithic.com/v1/cards/{card_token}

{
	"pin_status": "OK",
}

Change Card PIN

To change a card's PIN, card programs should follow the standard PIN change behavior by using the Lithic Update Card endpoint.

You can learn more about updating a card with example requests and responses here: API Guide reference.

There are no additional actions required for the PIN change to unblock the PIN. Changing the PIN will always unblock a blocked offline PIN.

Request

PATCH https://api.lithic.com/v1/cards/{card_token}

{
	"pin":"ENCRYPTED_PIN_BLOCK_STRING"
}