Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-261190449.2 KB
Cards

Replace Card

Replace or renew an existing card. This endpoints terminates the card being replaced and creates a new card with the same settings and card type, but different sensitive card information under the same cardholder. This can be useful to replace for instance a stolen credit card. The following callbacks will be triggered by this action:

  • For the terminated card: CARD_TERMINATED, CARD_STATUS_CHANGED to terminated and CARD_BALANCE_UPDATED to set the card balance to zero.
  • For the newly created card: CARD_ISSUED, CARD_ACTIVATED, CARD_STATUS_CHANGED and CARD_BALANCE_UPDATED with the corresponding balance.
post/cards/{cardId}/replace

Path parameters

cardIdstring uuid required

The unique identifier of the card.

Request body

terminateCardReason'DAMAGED' | 'EXPIRING_SOON' | 'LOST' | 'STOLEN' | 'OTHER' required

The reason why the card is being replaced. Depending on the card type there are different valid reasons.

DAMAGED can be used for physical cards. EXPIRING_SOON can be used for physical and virtual cards, plus the cards has to expiry within the next three months. LOST can be used for physical cards. STOLEN can be used for all types of cards. OTHER can be used for all types of cards.

A replacement of a card is only possible if the card is not in one of the following statuses: PENDING_ISSUANCE, PENDING_REGISTRATION, REQUESTED. Also, single-use cards cannot be replaced at all.

expiryPeriodMonthsinteger required

The number of months the new card should be valid for. This needs to follow the guidelines from normal card issuing.

Response

Ok

cardIdstring uuid
type'VIRTUAL' | 'SINGLE_USE' | 'PHYSICAL' | 'BLACK' | 'TRAVEL' nullable

Deprecated, please use cardConfig instead. VIRTUAL - Virtual credit card SINGLE_USE - One-time virtual credit card (only one authorization allowed per card) PHYSICAL - Physical credit card BLACK - Physical black premium credit card TRAVEL - Virtual cards used specifically in travel industry related use cases

cardholderIdstring uuid
organizationIdstring uuid
limitRenewFrequency'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'TOTAL'
  • DAILY - The card limit is renewed every day
  • WEEKLY - The card limit is renewed every week
  • MONTHLY - The card limit is renewed every calendar month
  • QUARTERLY - The card limit is renewed every calendar quarter
  • ANNUAL - The card limit is renewed every year
  • TOTAL - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.
expiryDatestring date-time
labelstring nullable

Available only for virtual cards with a cardConfig containing VIRTUAL or TRAVEL. The maximum length is 40 characters.

purposestring nullable

Available only for cards with type SINGLE_USE

cardDesignstring
cardDesignIdstring uuid

The unique identifier of the card design used for this specific card.

productRefstring

This field is deprecated and will be removed in the future. Use cardDesignId instead.

platformFeeboolean
cardConfigstring

Please contact your Pliant contact person for details

replacedByCardIdstring uuid

Filled, if this card was replaced by another card.

replacedCardIdstring uuid

Filled, if this card replaced another card.

replacementReason'DAMAGED' | 'EXPIRING_SOON' | 'LOST' | 'OTHER' | 'STOLEN'

Describes the reason for the card replacement.

cardAccountIdstring uuid

The unique identifier of the card account.