Z Zise Developers 简体中文
Card Issuance › Guides

Apply, review, then issue. Physical cards also require binding and activation; activation is irreversible.

Issue Cards

Standard starting point for merchant-hosted accounts: Quick KYC Card Issuance. For merchant_hosted accounts, bind a profile for the product, explicitly pass the same binding to the quote and application, and use funding_source: merchant.

Virtual Cards


POST /v1/cards/applications   { "product_id": "…", "source_asset": "USDT", "funding_source": "merchant" }
GET  /v1/cards/applications/{id}

Approval sends card.application.approved. If the application includes first_topup, a separate card.topup.credited event is sent when the initial funds reach the card (the same event used for a later POST /v1/cards/{id}/topups). When the card issuer sends us a 3DS / OTP verification code, we send a separate card.3ds.received event. The event's data.id is the public card resource ID (crd_<id>). It includes otp_code, expires_at, and, where an originating application exists, its public-format application_id. Merchants can correlate it with their member, card, and application records. It does not disclose the upstream provider or our internal event_key. For a WAS physical card that we automatically activate after receiving the 3DS activation code, an additional card.activated event is sent. Its data.id is also the public card resource ID (crd_<id>). The payload includes activation_mode=auto_3ds and initial_pin, allowing the merchant to show the initial PIN to the user.

In GET /v1/cards/{id}, the auto_activation field indicates platform-managed activation. When true, wait for the activation result after binding; the user does not need to submit activation again or choose a PIN. Codes received before or after binding are handled by the platform. Binding acceptance, card.bound, and card.3ds.received are not proof of activation: show success only after the card status is confirmed as active.

The platform-operated personal-KYC flow requires the member's own L1 by default. One manual review is sufficient: after GET /v1/kyc reports approved, change product_id to apply for other card products directly. There is no need to call POST /v1/kyc/applications again. If another product's identity-document type or issuing-country requirements do not match the approved profile, the card application is rejected. That is an eligibility issue, not a requirement to repeat identity verification.

If the merchant enables Quick KYC, a member without genuine L1 verification can also obtain a card: the system exclusively binds an approved profile from the profile pool (profile fees follow the merchant configuration) and uses it to create a cardholder with the issuer. The level returned by GET /v1/kyc remains 0, and Express Remittance remains unavailable. See Quick KYC.

This is different from the card-issuing Quick Application flow for blind issuance of physical cards from inventory.

Application Confirmation: Obtain a Quote First


GET /v1/cards/products/{id}/quote

Retrieve the issuing fee, shipping fee for the address, and the member's eligibility in one request. Without this step, the end user would see the price for the first time only after POST /v1/cards/applications has already charged them.

min_first_topup in the response is this product's minimum initial top-up, a human-readable amount in the same form as issue_fee. Pass it unchanged as first_topup when applying. A lower amount returns 400 amount_out_of_range and no application is created. "0.00" means the product has no initial-top-up minimum, so first_topup may be omitted.

⚠ Keep issue_fee and shipping_fee separate; do not combine them into a single price: burying shipping in the issuing fee means a user seeing a 20 USD physical card cannot tell that part of the price pays for delivery. Likewise, a free-shipping claim must depend on shipping_fee == 0. Hardcoding that claim promises something our operations team can change at any time.

The shipping country affects shipping fees only, not issuing-country restrictions. Any shipping address already belonging to the member can be selected; in shipping_by_address, deliverable is true and reason is empty. Product country allowlists and blocklists check only the regular or Quick KYC profile used for this application, identically for virtual and physical cards.

⚠ When can_apply: false, a reason is provided. Missing identity verification should lead to the verification flow; card_address_required should lead to adding a shipping address; provider unavailability should show a try-again-later message. These require three distinct responses. A generic unavailable message leaves the user stranded.

Physical Cards

Shipping Addresses for Platform-Operated Accounts

Platform-operated physical card issuance requires a shipping address belonging to the member; applications without one are rejected. Non-platform-operated merchant_hosted merchants fulfill their own cards and do not need to create a shipping address with us first. Follow the merchant Quick KYC flow, then bind and activate the card.

The address-book steps below apply to flows that require a shipping address with us:


GET    /v1/shipping-addresses
POST   /v1/shipping-addresses
POST   /v1/shipping-addresses/{id}/default

The first address automatically becomes the default, so the shortest flow is to create one and then place the order. Supply address_id to select a specific address; omit it to use the default.

⚠ If an explicitly supplied address_id cannot be resolved, the request is rejected immediately, without silently falling back to the default address.

Shipping to the wrong destination cannot be undone.

⚠ The address is snapshotted into the order when it is placed. Subsequent address edits or deletions

do not redirect a parcel in transit or alter the address recorded on historical orders.

There are two additional stages:


申请 ─► 制卡 ─► 可绑定 ─► 绑卡 ─► 激活

Approved downstream inventory-based physical-card applications automatically enter awaiting_bind (in-person handover, bypassing our awaiting-shipment stage). Platform-operated applications still use manual shipping or in-person fulfillment.

StageEndpointKey points
BindPOST /v1/cards/bindFull card number, expiry, and security code. Do not send only the last four digits. No step-up authentication
ActivatePOST /v1/cards/{id}/activateBind first, then call this with the crd_ from card.bound. Expiry plus PIN. Irreversible. PIN length depends on the card product; some physical cards require 6 digits

Downstream merchants receive card.application.awaiting_bind when an application enters awaiting_bind (standard inventory applications automatically complete in-person handover after approval; platform-operated applications require confirmation of in-person handover or delivery receipt). Retrieve the application details, then bind and activate the card. This does not mean card issuance is complete or the card is usable. Platform-operated members do not receive this event.

After the bind finishes and the card row exists, merchants receive card.bound. data.id is the public card id (crd_<id>) and the status is unactivated. When the card comes from an application, the event also includes application_id (cap_<id>). Retrieve it with GET /v1/cards/{id}, then activate. This is not activation. Platform-operated members do not receive this event.

⚠ Binding does not require step-up authentication because the three identifying details are themselves proof of possession:

the user has the card. Activation is irreversible, but OpenAPI no longer redirects the end user to

our hosted page. The merchant completes verification within its own domain, then calls the endpoint directly.

Shipping


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

The four status axes—application, inventory, shipping, and card—advance independently. None is derived from another. Do not infer that a card is usable from delivered shipping status: the member may not have activated it yet.

Related Endpoints