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
- Card services, Quick KYC, and the target product must be enabled for the merchant. Merchant prefunding must cover the profile fee, issuance cost, and initial top-up. Contact the platform to enable missing services; creating a member does not enable them automatically.
- The API Key needs
members:write,kyc:read,kyc:write,cards:read, andcards:write. Obtain a token and sign requests as described in Authentication and Signing. - Member requests must use the same merchant credentials and
x-on-behalf-of, set to your ownexternal_member_idor the returnedmem_…. Never use another merchant's product, member, or binding IDs. - Use a different UUID v4
x-idempotency-keyfor each independent POST operation. After a network timeout or unknown outcome, query the result or retry with the original body and key.
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.
| Response | Meaning | Action |
|---|---|---|
200, reused: true | Existing compatible binding reused; no new profile fee | Save the returned binding.id |
201, reused: false | New binding; the profile fee has been charged | Save 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.
- Explicitly set
funding_sourcetomerchant. Omitting it or sendingmemberreturnsinvalid_fields. Merchant-hosted accounts pay from actual merchant prefunding, not deposits into a member wallet. - With
product_id, the product determines the card type andform_factormay be omitted. If provided, the application parameter usesvirtualorphysicaland must agree with the product. Some query responses usevirtual_card/physical_card; do not copy these values directly into the application parameter. client_keyis your stable business key for this card order. Keep it for network retries rather than creating a second order. Use a new business key when selecting a different product and placing a new order.- Issuance fees, initial top-ups, and profile fees are handled separately. Reusing a bound profile does not charge another profile fee, but each new card application is still charged according to its product rules.
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 type | Next steps |
|---|---|
| Virtual | Wait for the issuance result, then query GET /v1/cards/{id} using card_id to confirm the card state; confirm any initial top-up separately |
| Physical | Follow 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 event | Action |
|---|---|
quick_kyc_disabled | Contact the platform to enable Quick KYC for this merchant |
quick_kyc_unpaid | Check merchant prefunding, card service enablement, and funding restrictions; resolve them before submitting again |
quick_kyc_exhausted | No compatible profile is available; contact the platform rather than repeatedly applying |
quick_kyc_limit | The active binding limit has been reached; inspect existing bindings |
request_rejected with an error field identifying email | The email has been used; supply an eligible new email. Other rejection reasons must not all be treated as email errors |
card_country_not_supported | The 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_available | Check this merchant's product authorization, enabled state, asset, and card type; retain request_id when contacting the platform |
invalid_fields | Correct the reported field, such as email, funding_source, or an invalid binding |
kyc.quick.compensated | The 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.