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"
}
'import requests
url = "https://api.fyatu.com/api/v3/cards/{cardId}/replace"
payload = {
"reason": "Card compromised",
"reference": "replace-card-abc123"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Card compromised', reference: 'replace-card-abc123'})
};
fetch('https://api.fyatu.com/api/v3/cards/{cardId}/replace', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3/cards/{cardId}/replace",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Card compromised',
'reference' => 'replace-card-abc123'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3/cards/{cardId}/replace"
payload := strings.NewReader("{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3/cards/{cardId}/replace")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3/cards/{cardId}/replace")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}Cards
Replace Card
Replace a card with a new one — same cardholder, new card number. POST /cards//replace.
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"
}
'import requests
url = "https://api.fyatu.com/api/v3/cards/{cardId}/replace"
payload = {
"reason": "Card compromised",
"reference": "replace-card-abc123"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Card compromised', reference: 'replace-card-abc123'})
};
fetch('https://api.fyatu.com/api/v3/cards/{cardId}/replace', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fyatu.com/api/v3/cards/{cardId}/replace",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'Card compromised',
'reference' => 'replace-card-abc123'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fyatu.com/api/v3/cards/{cardId}/replace"
payload := strings.NewReader("{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fyatu.com/api/v3/cards/{cardId}/replace")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fyatu.com/api/v3/cards/{cardId}/replace")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"Card compromised\",\n \"reference\": \"replace-card-abc123\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}Overview
Replace an existing card with a brand new one. ThecardId 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
| Parameter | Type | Description |
|---|---|---|
cardId | string | The unique card identifier |
Request Body (Optional)
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | No | Reason for replacing the card (e.g., “Card compromised”, “Card lost”) |
reference | string | No | Your 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";
}
const cardId = 'crd_8f3a2b1c4d5e6f7890abcdef12345678';
const response = await fetch(`https://api.fyatu.com/api/v3/cards/${cardId}/replace`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
reason: 'Card compromised',
reference: 'replace-card-abc123' // Optional: your unique reference
})
});
const result = await response.json();
if (result.success) {
console.log('Card replaced successfully!');
console.log('New Last 4:', result.data.last4);
console.log('New Expiry:', result.data.expiryDate);
console.log('Balance Transferred: $' + result.data.balance);
console.log('Reference:', result.data.reference);
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | The card identifier (unchanged from before) |
cardholderId | string | The cardholder identifier |
name | string | Name on the card |
last4 | string | Last 4 digits of the new card number |
maskedNumber | string | Masked new card number |
expiryDate | string | New card expiry date (MM/YYYY) |
brand | string | Card brand (VISA or MASTERCARD) |
status | string | Card status (always ACTIVE for new cards) |
balance | number | Current balance transferred from old card |
reference | string | Your reference for this operation |
replacedAt | string | ISO 8601 timestamp of when the card was replaced |
Error Responses
| Status | Error Code | Description |
|---|---|---|
| 400 | CARD_TERMINATED | Cannot replace a terminated card |
| 400 | INSUFFICIENT_BALANCE | Business wallet has insufficient balance for replacement fee |
| 404 | CARD_NOT_FOUND | Card not found or doesn’t belong to your app |
| 500 | REPLACE_FAILED | Failed 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
JWT access token obtained from /auth/token
Path Parameters
The unique card identifier
Body
application/json

