Issue Cards

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

Virtual Cards


POST /v1/cards/applications   { "product_id": "…", "source_asset": "USDT" }
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.

The member's own L1 verification is required 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 (10 USDT on first use) 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.

⚠ 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

Prerequisite: The Member Must Already Have a Shipping Address

Without one, POST /v1/cards/applications is rejected immediately—the card is a physical item that needs delivery.


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.

Stage	Endpoint	Key points
Bind	`POST /v1/cards/bind`	Three identifying details, including the last four card digits; no step-up authentication required
Activate	`POST /v1/cards/{id}/activate`	Irreversible; merchants complete their own verification and call OpenAPI directly

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.

⚠ 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.