/
5 minute read
November 24, 2021

Managing Lost, Stolen, or Damaged Cards

Hidden

You might need to limit, suspend, terminate and reissue, or replace a card if it is lost, damaged, or stolen. You can perform these actions on physical and virtual cards, as well as on any digital wallet tokens sourced from the affected card.

Note that the state of any digital wallet token is independent from the state of its source card and independent from all other digital wallet tokens, even if they share the same source card. For example, in order to suspend a card and two digital wallet tokens sourced from that card (say, one provisioned to a phone and one to a laptop), you would make three API calls — one for the card and one for each digital wallet token.

Stolen cards

If a card is stolen, you should terminate and reissue it.

To terminate a card, send a POST request to the /cardtransitions endpoint and set the state field to TERMINATED. Terminating a card terminates all cards that have the same PAN but does not terminate associated digital wallet tokens.

When reissuing a new card for a stolen card, the reissued card should have a new PAN, CVV2, and expiration date. Optionally, you can copy the PIN from the old card to the new card. You can also reassign all digital wallet tokens associated with the stolen card to the new card (this option eliminates the need to terminate the tokens and then provision new ones).

To reissue a card with a new PAN (and move the PIN and digital wallets tokens from the old card to the new card), send a POST request to the /cards endpoint. In the request, set both the translate_pin_from_card_token and activation_actions.swap_digital_wallet_tokens_from_card_token fields to the value of the old card’s token field.

You must also set the required user_token and card_product_token fields to appropriate values. Note that the digital wallet tokens are not reassigned until the reissued card is activated.

To terminate a digital wallet token, send a POST request to the /digitalwallettokentransitions endpoint and set the state field to TERMINATED.

Lost cards

If a card is lost, you should limit, suspend, or terminate and reissue it. To learn about card terminations, see Stolen cards.

Suspending a card suspends all cards that have the same PAN but does not suspend associated digital wallet tokens (every token has a unique PAN). To suspend a card, send a POST request to the /cardtransitions endpoint and set the state field to SUSPENDED. To suspend a digital wallet token, send a POST request to the /digitalwallettokentransitions endpoint and set the state field to SUSPENDED.

The LIMITED card state is a type of card suspension: the card is suspended except for card-on-file transactions such as installment payments or recurring charges. To limit a card, send a POST request to the /cardtransitions endpoint and set the state field to LIMITED. There is no LIMITED state for digital wallet tokens.

To reactivate a limited or suspended card, or a suspended digital wallet token, send a POST request to the same endpoint used for suspending it and set the state field to ACTIVE.

Damaged cards

If a card is damaged, replace the card. A replaced card has the same PAN as the old card but a new CVV2 and expiration date. The damaged card does not need to be suspended or terminated immediately.

To replace a card, send a POST request to the /cards endpoint and set the reissue_pan_from_card_token field to the value of the old card’s token field. This action creates a new card with the same PAN as the old card but with a new CVV2 and new expiration date. All associated digital wallet tokens are reassigned to the new card when it’s activated.

Tip
  • You can replace only the most recent in a chain of replaced cards.

  • You can tokenize only the most recent in a chain of replaced cards.

  • You can replace a card only to the original user.

  • You cannot replace a physical card with a virtual card.

  • You can replace a virtual card with a physical card.

Feedback on this page?

If you feel we can do anything better, please let our team know.