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

Document supplements: obtain a hosted-screen link for the end user

POST /v1/cards/applications/{id}/supplement-sessions scope: cards:write
On behalf of a member · x-on-behalf-of required Requires x-idempotency-key

When an application enters need_docs because the upstream requires additional cardholder documents, use this endpoint to obtain a single-use URL for our hosted screen and pass it to the end user. They retake and upload identity-document photos there; after submission, your application continues automatically without further API calls from you.

── Why a hosted screen rather than a JSON submission endpoint ── On this business line, submitting supplements actually means replacing document images. Photos sent upstream come from the member's current KYC profile, not from fields in the submission body. A scalar-only endpoint would consume the supplement attempt while submitting the same old photos again: the user would see Submitted, then receive another rejection for the same reason. This process is one-shot: when the case expires, the application becomes failed, the issuance fee is refunded, and no card is issued.

Images follow the same boundary as KYC: they never pass through your servers. You receive only a URL.

── Three constraints on the link ── Bound to the member and this specific case, single-use, valid for 24 hours. It expires on successful submission. Validation errors do not consume it; the user may correct input on the same page.

⚠ Do not cache and reuse this link. It can submit documents on behalf of that member. Request a fresh link for each submission session; a request costs far less than retaining a permanent privileged link.

⚠ A ticket can be issued only when supplement.status from GET /v1/cards/applications/{id} is pending. Once submitted (submitted), returns 404. Issuing another link would only direct the user to an expired-link screen.

⚠ Name / date of birth / document number / residential address cannot be changed on this screen. The page states this and explains where to make the changes. Identity-data changes require a new KYC review, but replacing a photo with a clearer one does not. Requiring review for the latter would stop this member's transfers / wealth products / remittances because of insufficient KYC level, solely to address one issuer's image-quality concern.

Prerequisites

  • The application has a document-supplement case with status = pending.

Path Parameters

FieldTypeRequiredDescription
id string Required Application ID. Accepted with or without the cap_ prefix.
FieldTypeRequiredDescription
x-idempotency-key string Required
x-on-behalf-of string Required The member on whose behalf to call. Must own this application; otherwise returns 404.

Response

201Ticket issued
{
  "id": "kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "hosted_url": "https://api.zinfra.vip/hosted/card-supplement/kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "expires_at": 1786000000
}
400idempotency_key_required · idempotency_key_invalid · member_context_required · member_not_found
404not_found: the application does not exist, does not belong to this member/merchant, or has no outstanding document-supplement case. All four cases return the same response, without distinction; distinguishing them would enable probing application status.
Request 
curl -X POST 'https://api.zinfra.vip/v1/cards/applications/{id}/supplement-sessions' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY'
const res = await fetch("https://api.zinfra.vip/v1/cards/applications/{id}/supplement-sessions", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
  },
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();
import requests

res = requests.post(
    "https://api.zinfra.vip/v1/cards/applications/{id}/supplement-sessions",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
    },
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()
req, _ := http.NewRequest("POST", "https://api.zinfra.vip/v1/cards/applications/{id}/supplement-sessions",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
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/applications/{id}/supplement-sessions"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
// Use String / BigDecimal for amounts, not double.
$ch = curl_init('https://api.zinfra.vip/v1/cards/applications/{id}/supplement-sessions');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
  ],
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
201 
{
  "id": "kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "hosted_url": "https://api.zinfra.vip/hosted/card-supplement/kyc_9f2c81a4d7e34b06b1c5a83e7d420f6e",
  "expires_at": 1786000000
}