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": "Alice Example",
    "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

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

ParameterTypeDescription
cardIdstringThe unique card identifier

​
Request Body (Optional)

FieldTypeRequiredDescription
reasonstringNoReason for replacing the card (e.g., “Card compromised”, “Card lost”)
referencestringNoYour unique reference for this operation. Defaults to cardId if not provided. Returned in webhooks for easy reconciliation.

​
Example Usage

<?php
$cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';
$data = [
    'reason' => 'Card compromised',
    'reference' => 'replace-card-abc123'  // Optional: your unique reference
];

$ch = curl_init("https://api.fyatu.com/api/v3/cards/{$cardId}/replace");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($data)
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    echo "Card replaced successfully!\n";
    echo "New Last 4: " . $result['data']['last4'] . "\n";
    echo "New Expiry: " . $result['data']['expiryDate'] . "\n";
    echo "Balance Transferred: $" . $result['data']['balance'] . "\n";
    echo "Reference: " . $result['data']['reference'] . "\n";
}

​
Response Fields

FieldTypeDescription
idstringThe card identifier (unchanged from before)
cardholderIdstringThe cardholder identifier
namestringName on the card
last4stringLast 4 digits of the new card number
maskedNumberstringMasked new card number
expiryDatestringNew card expiry date (MM/YYYY)
brandstringCard brand (VISA or MASTERCARD)
statusstringCard status (always ACTIVE for new cards)
balancenumberCurrent balance transferred from old card
referencestringYour reference for this operation
replacedAtstringISO 8601 timestamp of when the card was replaced

​
Error Responses

StatusError CodeDescription
400CARD_TERMINATEDCannot replace a terminated card
400INSUFFICIENT_BALANCEBusiness wallet has insufficient balance for replacement fee
404CARD_NOT_FOUNDCard not found or doesn’t belong to your app
500REPLACE_FAILEDFailed to replace card at the bank partner
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