Skip to main content
POST
/
cards
/
{cardId}
/
replace
Replace Card
curl --request POST \
  --url https://api.fyatu.com/api/v3/cards/{cardId}/replace \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "Card compromised",
  "reference": "replace-card-abc123"
}
'
{
  "success": true,
  "status": 200,
  "message": "Card replaced successfully",
  "data": {
    "id": "crd_8f3a2b1c4d5e6f7890abcdef12345678",
    "cardholderId": "ch_abc123def456",
    "name": "John Doe",
    "last4": "7890",
    "maskedNumber": "****7890",
    "expiryDate": "01/2029",
    "brand": "MASTERCARD",
    "status": "ACTIVE",
    "balance": 150,
    "reference": "replace-card-abc123",
    "replacedAt": "2026-01-17T10:00:00+00:00"
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-01-17T10:00:00+00:00"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Issue a replacement card for an existing card. The old card is terminated and its remaining balance is transferred to the new card automatically. The new card keeps the same productId, cardholder, and name.

​
Path Parameters

ParameterTypeDescription
cardIdstringThe card ID to replace

​
Behavior

  1. Old card is terminated immediately
  2. Remaining balance is transferred to the new card
  3. New card is issued with a new card number, CVV, and expiry date
  4. New card carries the same productId (and thus the same settings)
  5. A card.replaced webhook is sent when complete

​
When to Use Replace

ScenarioRecommended Action
Card number compromisedReplace
Card expiring soonCards auto-renew — no action needed
Cardholder wants a fresh numberReplace
Card lost (uncertain if fraudulent)Freeze first, then replace if not recovered

​
Error Codes

CodeDescription
RESOURCE_NOT_FOUNDCard not found or belongs to another business
CARD_NOT_ACTIVEOnly active cards can be replaced
PROVIDER_ERRORCard provider rejected the replacement
The replacement card may briefly have status: PROCESSING. Listen for the card.replaced webhook for the new card details.

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