Z Zise Developers
/
简体中文
Card Issuance › API Reference › Lifecycle

Replacement progress or replacement quote (mutually exclusive sections)

GET /v1/cards/{id}/replacement scope: cards:read
On behalf of a member · x-on-behalf-of required

Returns one of two mutually exclusive sections: progress (replacement) when a replacement order is in progress, or pricing (quote) when there is none. Separate endpoints would require an initial request just to know which one to call.

replacement is null when there is no replacement in progress; the field is not omitted. status has eight values; display unknown values unchanged, rather than defaulting to processing. For is_security: true cases (exposed card number / fraudulent use), the original card is frozen first.

⚠ Display card_balance and held together in quote. Replacement returns the card balance to the available balance, and the upstream has no card-to-card transfer API. Funds do not move to the new card. These two figures explain where the existing card's funds went; omitting either can mislead the user.

⚠ replace_fee equals the issuance fee. There is no separate price tier; the card fee must be paid again for replacement.

⚠ For virtual cards, quote is always null. Only physical cards support replacement; close a lost virtual card and issue a new one.

Path Parameters

FieldTypeRequiredDescription
id string Required
FieldTypeRequiredDescription
x-on-behalf-of string Required

Response

200OK
{
  "replacement": null,
  "quote": {
    "replace_fee": "20000000",
    "fee_asset": "USD",
    "card_balance": "35.20",
    "held": "0.00"
  }
}
404not_found: the card does not exist or does not belong to this member/merchant.
Request 
curl -X GET 'https://api.zinfra.vip/v1/cards/{id}/replacement' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID'
const res = await fetch("https://api.zinfra.vip/v1/cards/{id}/replacement", {
  method: "GET",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
  },
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();
import requests

res = requests.get(
    "https://api.zinfra.vip/v1/cards/{id}/replacement",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()
req, _ := http.NewRequest("GET", "https://api.zinfra.vip/v1/cards/{id}/replacement",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zinfra.vip/v1/cards/{id}/replacement"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
// Use String / BigDecimal for amounts, not double.
$ch = curl_init('https://api.zinfra.vip/v1/cards/{id}/replacement');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
  ],
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
200 
{
  "replacement": null,
  "quote": {
    "replace_fee": "20000000",
    "fee_asset": "USD",
    "card_balance": "35.20",
    "held": "0.00"
  }
}