Skip to main content
POST
Replace Card

Overview

Replace an existing card with a brand new one. The cardId remains the same for your records, but the card details (number, expiry, CVV) are replaced with a completely new card. Any remaining balance is automatically transferred to the new card.
The old card will be immediately terminated and cannot be used after replacement. All future transactions must use the new card details.

Use Cases

  • Card Compromised: When a cardholder reports unauthorized use or data exposure
  • Card Lost: When a physical card is lost and needs to be replaced
  • Card Damaged: When the card details are no longer accessible

Path Parameters

Request Body (Optional)

Example Usage

Response Fields

Error Responses

The cardId stays the same after replacement, so you don’t need to update your database references. Only the card details (number, expiry, CVV) change.
Product Fallback: When replacing a card, the system first tries to issue the same card product type. If that product is no longer available for issuance (i.e., canIssue: false in the products list), the default product (isDefault: true) is automatically used instead. The replacement is seamless — the balance is transferred regardless of which product is used.
A card replacement fee may apply based on your pricing configuration. Use the Get Pricing endpoint to check current fees.

Authorizations

Authorization
string
header
required

JWT access token obtained from /auth/token

Path Parameters

cardId
string
required

The unique card identifier

Body

application/json
reason
string

Reason for replacing the card (e.g., 'Card compromised', 'Card lost', 'Card damaged')

Maximum string length: 255
reference
string

Your unique reference for this operation. Defaults to cardId if not provided. Returned in webhooks for easy reconciliation.

Maximum string length: 100

Response

Card replaced successfully

success
boolean
Example:

true

status
integer
Example:

200

message
string
data
object
meta
object