Z Zise Developers 简体中文
Card Issuance › Guides

The standard flow for merchant-hosted accounts: create a member, bind a product-compatible Quick KYC profile, quote and apply with the same binding, and pay from merchant prefunding.

Merchant-Hosted Accounts: Quick KYC Card Issuance

All non-platform-operated merchant_hosted merchants should integrate Quick KYC card issuance using this chapter. Virtual and physical cards share the profile-binding and funding flow; fulfillment after application depends on the card type.

Standard sequence: create member → select product → bind or reuse Quick KYC profile → quote with the binding → apply with merchant funding → query application and card status.

Prerequisites

This chapter defines the standard merchant integration flow; the API does not forcibly replace a member's submitted personal KYC. Explicitly pass the selected quick_kyc_binding_id to both the quote and application to select Quick KYC for this request.

Step 1: Create the Member

Call POST /v1/members:


{
  "external_member_id": "member-10086",
  "email": "member10086@example.com"
}

Save the returned member id. Subsequent member requests use x-on-behalf-of: member-10086, or the returned mem_…. Your own system assigns the external member ID; another merchant's prefix is not required.

Successful creation means the member exists, not that personal KYC is approved. Quick KYC card issuance does not require prior personal L1 submission. Members with personal L1 / L2 can also follow this flow; their existing verified profile and level remain unchanged.

Step 2: Select the Card Product

Call GET /v1/cards/products, select a product visible to the current merchant that supports Quick KYC, and save its returned id. Use this same cpd_… in subsequent steps. Exclude products requiring L2 before allocating a paid profile, as they do not support this flow.

Product IDs, fees, supported funding assets, and minimum initial top-ups come from current API responses and configuration. Do not copy another merchant's product ID or infer virtual versus physical from the BIN alone.

Step 3: Bind or Reuse a Profile for the Product

Optionally call GET /v1/kyc/quick to inspect the member's active bindings. Then call POST /v1/kyc/quick to select a profile compatible with the target product:


{
  "card_product_id": "cpd_42",
  "email": "member10086+card01@example.com"
}

cpd_42 is an example; replace it with the product ID from step 2. Use an email where you or the member can receive notifications. A new allocation requires a full email address never used by any personal KYC, Quick KYC, or historical profile. Member registration and KYC emails serve different purposes; successful registration does not establish eligibility for Quick KYC allocation with that email.

Keep the full email within 50 characters where possible. Comparisons ignore case and surrounding whitespace but preserve +card01. Confirm that the email service can receive an alias before using it.

ResponseMeaningAction
200, reused: trueExisting compatible binding reused; no new profile feeSave the returned binding.id
201, reused: falseNew binding; the profile fee has been chargedSave the returned binding.id

A compatible existing binding is reused first, needs no new email, and keeps its bound email unchanged. Each member may have up to 5 active bindings. A 201 from this endpoint means the profile is bound, not that a card application exists or a card has been issued.

The profile fee is paid from merchant prefunding at the merchant's configured rate. Do not hardcode the platform default or another merchant's rate. This binding endpoint does not require funding_source; the server selects funding according to the merchant account model.

Step 4: Quote with the Same Binding

Call GET /v1/cards/products/{id}/quote, passing the binding.id from step 3 as a query parameter:


GET /v1/cards/products/{id}/quote?quick_kyc_binding_id=7c9e6679-7425-40de-944b-e07fc1f90ae7

Replace {id} with the product ID from step 2. Check can_apply, reason, fees, funding assets, and min_first_topup. Resolve can_apply: false before submitting an application. A quote does not debit funds or guarantee that balances and product availability will stay unchanged.

Do not quote using personal KYC and then apply using Quick KYC; use the same binding for both requests. Country rules check the selected profile's address country, falling back to nationality if absent. Identity-document issuing country is a separate field and must not be confused with either. Products requiring L2 do not support the explicit Quick KYC application flow in this chapter. An explicit binding is rejected even when the member already has personal L2. Select a product supporting Quick KYC; if an L2 product is required, integrate its personal-verification flow separately.

Step 5: Apply with Merchant Prefunding

Call POST /v1/cards/applications:


{
  "product_id": "cpd_42",
  "quick_kyc_binding_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "source_asset": "USDT",
  "first_topup": "5",
  "funding_source": "merchant",
  "client_key": "member-10086-card-order-001"
}

Replace the product, binding, asset, and initial top-up with values confirmed in the preceding steps. The example amount 5 is not a fixed amount for every product. first_topup must meet min_first_topup.

Do not use automatic profile selection after omitting the binding as the standard integration: selection depends on whether the member already has personal KYC. Explicit bindings let L0, L1, and L2 members follow the same request sequence.

Step 6: Complete the Application and Card Lifecycle

Save the returned application id (cap_…) and query GET /v1/cards/applications/{id}. Verify signatures and deduplicate card application events, then query the latest state.

A card application 201 means accepted, not usable. Do not submit another order after an HTTP success response, and do not treat every state as waiting for issued.

Card typeNext steps
VirtualWait for the issuance result, then query GET /v1/cards/{id} using card_id to confirm the card state; confirm any initial top-up separately
PhysicalFollow product fulfillment. For inventory cards, call POST /v1/cards/bind after awaiting_bind, obtain the card ID, then activate as required and query its state

The merchant fulfills merchant_hosted physical cards; creating a shipping address with us is not required first. The platform-operated shipping-address requirement does not apply to this flow. A physical application may remain at pending_activation; continue with card activation instead of waiting indefinitely for the application to become issued. See Physical Card Binding and Activation.

Errors, Retries, and Profile Fees

Error or eventAction
quick_kyc_disabledContact the platform to enable Quick KYC for this merchant
quick_kyc_unpaidCheck merchant prefunding, card service enablement, and funding restrictions; resolve them before submitting again
quick_kyc_exhaustedNo compatible profile is available; contact the platform rather than repeatedly applying
quick_kyc_limitThe active binding limit has been reached; inspect existing bindings
request_rejected with an error field identifying emailThe email has been used; supply an eligible new email. Other rejection reasons must not all be treated as email errors
card_country_not_supportedThe selected profile's country does not meet the product rules. Select a compatible product or profile; personal KYC approval does not establish product country eligibility
product_not_availableCheck this merchant's product authorization, enabled state, asset, and card type; retain request_id when contacting the platform
invalid_fieldsCorrect the reported field, such as email, funding_source, or an invalid binding
kyc.quick.compensatedThe binding is no longer active and its profile fee was refunded; query active bindings again and follow step 3

After correcting a definitive 4xx rejection, submit with a new request idempotency key; the old key may replay the cached failure. For network timeouts, 5xx, or unknown outcomes, keep the original key and follow Idempotency and Retries to prevent duplicate orders.

Card failure does not guarantee a profile-fee refund. The platform may compensate an eligible first-use failure when there is no evidence of successful acceptance, no issued card, and no in-flight application. Rely on kyc.quick.compensated and actual accounting results. Active bindings can be used for compatible products; compensated bindings cannot be reused. Query issuance-fee and initial-top-up results separately; a profile-fee refund does not imply a full application refund.

Personal Verification Level and Other Services

A Quick KYC binding is for eligible card products only. It does not establish or overwrite the member's personal verified profile or increase the level returned by GET /v1/kyc. An L0 member with only a Quick KYC binding remains L0; do not treat the binding as personal L1 / L2 approval.

Complete personal verification as required by remittance and other services. See KYC Overview for platform-operated personal verification and Quick KYC for profile fields and binding rules.