Replace card

PATCH/issuing/cards/{card_id}/replace

Replace a card and automatically deactivate the original. The response contains the new replacement card; retrieve the original card to see its deactivation_reason and replacement_card_id.

Requested reason

PAN

Original card's recorded reason

Original card's tokens

lost, stolen, fraud, voluntary

New PAN

Requested reason

Deactivated

damaged

Reused

damaged

Deactivated

expired

Reused

renewed

Deactivated

All non-terminal tokens on the original card are deactivated for every replacement reason, including when the PAN is reused. Reusing the PAN increments sequence_number. An expired replacement records renewed as the reason, but does not preserve tokens. The separate renew endpoint migrates tokens when the renewal card is activated. renewed and account_closed are not valid replacement request reasons and return HTTP 400. A card can't be replaced as damaged or expired if any card with the same PAN was deactivated as lost, stolen, or fraud.

Path Parameters

card_id

stringRequired

Unique identifier for the card.

Body Parameters

deactivation_reason

enumRequired

Reason for deactivating the original card during replacement. lost, stolen, fraud, and voluntary requests create a replacement with a new PAN. damaged requests reuse the PAN. expired requests are processed as renewal-style replacements with the same PAN and a new expiration, and the original card's reason is recorded as renewed. All non-terminal card tokens on the original card are deactivated for every reason. renewed and account_closed are not accepted by this endpoint. Possible values: lost, stolen, fraud, expired, voluntary, damaged

encrypted_pin

stringOptional

Optional base64-encoded encrypted PIN

expiration_month

integerOptional

Optional expiration month (1-12)

expiration_year

integerOptional

Optional expiration year (4-digit year, e.g. 2025)

status

stringOptional

Optional status for the replacement card