Application, card, shipping, and supplementary-document states advance independently. This page lists all four state axes.

State Machines and Values

Card issuance has four independent state axes. None is derived from another:

⚠ Delivered shipping does not mean the card can be used. These are separate axes. After receiving the parcel,

the member must still bind and activate the card. Likewise, a terminal application status does not imply an active card:

physical cards remain unactivated after their application reaches its final stage.

1. Application States

Only Three Values at Order Creation

POST /v1/cards/applications returns a reduced status set containing only:

Subsequent Queries Expose the Full Internal Set

GET /v1/cards/applications/{id} returns unfiltered internal status values. You may encounter any of these 20 values:

In progress (15 states)

Terminal (5 states) — These do not change afterward:

⚠ pending in the creation response and pending_merchant_funds in a subsequent query describe the same condition.

The former is normalized; the latter is the internal value. Your status mapping must recognize both,

or an order queued for insufficient prepaid funds will appear as an unknown state in your system.

This inconsistency is recorded under Known Issues.

We will standardize on the normalized value. Treat pending_merchant_funds as pending now,

and you will not need to change your integration when that happens.

⚠ pending_activation is the effective final application stage for physical cards, despite appearing under in-progress states.

No code advances the application beyond it: activation updates the card axis.

Do not wait for the application to become issued before proceeding; that will never happen for a physical card.

Do Not Enumerate Every In-Progress State

Decide whether to keep polling by checking whether the status is one of the 5 terminal states. Do not enumerate in-progress states. We may add an in-progress state without notice. If your explicit list omits it, the order can silently disappear from your list, making the user believe their application is gone.

2. Card States

        ┌──────────── 会员自助 ────────────┐
pending → unactivated → active ⇄ frozen
                          │      ↑ ↓
                          │   freezing / unfreezing（过渡态）
                          │
                          ├─→ risk_frozen   风控冻结，**会员解不了**
                          ├─→ suspended     运营暂停，**会员解不了**
                          ├─→ lost → reissuing → replaced
                          ├─→ expired
                          └─→ closing → closed

⚠ frozen permits top-ups; transitional states do not. This is intentional: freezing stops spending,

not incoming funds. During freezing / unfreezing, the card's state is unsettled,

so funding it would send money into a card with an uncertain status.

⚠ Freezing and unfreezing are separate transitions, not a shared processing state.

Combining them caused a production issue with invalid-card-status errors and failed top-ups after unfreezing.

⚠ Do not show an Unfreeze button for risk_frozen or suspended.

Member attempts will fail. Risk-control and operations teams respectively remove these restrictions.

Handling transitions: for freezing / unfreezing / pending / closing / reissuing, wait. Do not issue another command; repeated freeze requests do not accelerate completion.

3. Shipping States

There are 15 states. Our operations team updates them; polling does not advance them. While a parcel is in transit, the server does not progress automatically. Polling every 45 seconds merely wastes requests.

In transit: draft · created · awaiting_pickup · in_transit · out_for_delivery · returning

Exceptions (surface these separately for operations; buried in an in-transit list, they can remain unattended indefinitely): address_issue · delivery_failed · stalled · refused · returning · lost · damaged

Terminal: received · returned · lost · damaged

There is also delivered (the carrier reports delivery), which is not terminal. received, meaning the member confirmed receipt, is terminal.

⚠ Returned parcels never automatically return to available inventory. Processing after returned follows a separate flow,

outside this state axis.

4. Supplementary Documents

When an application enters need_docs, supplement in its details changes from null to an object:

"supplement": {
  "status": "pending",
  "required_items": ["cert_front", "address"],
  "deadline": "2026-08-20T00:00:00.000Z",
  "submit_url": ""
}

Without an outstanding request, supplement is null, not an omitted field.

Values of required_items

cert_front · cert_back · address · name · birth · cert_id · other

⚠ If we do not recognize the upstream reason, we return ["other"], never an empty array.

A documents-required screen with no listed items leaves users unable to determine what to submit.

Handle unknown items similarly: display Other documents; contact support.

deadline Is Enforced

After expiry, the application becomes failed and the issuing fee is refunded. This deliberately differs from remittance supplements, which return null for their deadline; card applications have a fixed database deadline.

You can safely use it for a countdown. An empty string means legacy data has no expiry configured.

How to Submit: Obtain a Hosted-Page Link

POST /v1/cards/applications/{id}/supplement-sessions
→ 201 { "hosted_url": "https://…/hosted/card-supplement/kyc_…", "expires_at": … }

Give hosted_url to the end user. They retake and upload their document images on that page, and the application resumes automatically after submission. You do not need another API call.

submit_via in the details always contains this endpoint name, not a ready-to-use URL: The link is single-use, bound to the member and request, and valid for 24 hours. Including it in application details would effectively make it persistent: details are repeatedly read, logged, and forwarded, yet that URL permits document submission as the member. Request it only when documents are about to be submitted.

⚠ A ticket is issued only when supplement.status is pending. If documents have already been submitted

(submitted), the endpoint returns 404. Issuing another link would give the user an entry point

that can only report the link as expired.

Why a Hosted Page Instead of a JSON Submission Endpoint?

Submitting documents here means replacing identity-document images. The images sent upstream come from the member's current verified identity profile, not fields in a submission body. Therefore:

• Images share the KYC boundary and never pass through your servers;
• An endpoint accepting only scalar values would consume this supplement request and resend the same old photographs, show Submitted to the user, and then receive a second rejection for the same reason. This flow is single-use: once the request expires, the application becomes failed, the issuing fee is refunded, and no card is issued.

⚠ Items such as name / birth / cert_id / address

cannot be changed on this page, which clearly indicates this. Identity changes require renewed identity review;

replacing a photograph with a clearer one does not. Requiring review for a better photograph would suspend this member's transfers, wealth products, and

remittances for insufficient verification level merely to satisfy one issuer's image-quality request.

Direct users to your support team for these items.

Failure Reasons (failure_code)

Details for terminal failed / rejected applications include failure_code. It uses public error-code mappings, not internal codes. Internal codes disclose implementation details; exposing them would turn the internal state machine into a public contract.

If a specific reason is unavailable, the value is an empty string, not null.

Related Endpoints

• GET /v1/cards/applications/{id}
• GET /v1/cards/{id}
• GET /v1/cards/applications/{id}/shipment