Z Zise Developers English
卡发行 › 指南

申请 → 审核 → 开卡。实体卡多绑卡与激活两步,且激活不可逆。

开卡

虚拟卡


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

申请通过后发 card.application.approved。带了 first_topup 的,首充到卡后再发一条 card.topup.credited(与事后 POST /v1/cards/{id}/topups 同一条事件)。发卡上游把 3DS / OTP 验证码回调给我方时,会单独发一条 card.3ds.received,事件体的 data.id 直接就是公开卡资源 ID(crd_<id>),并会带 otp_code、expires_at,以及在有申请单来源时额外带公开格式的 application_id,供商户按自己已有的会员/卡/申请单坐标做关联;不会暴露上游 provider 或我方内部 event_key。WAS 实体卡若由我方在收到 3DS 激活码后继续自动激活,还会额外再发一条 card.activated,其中 data.id 同样是公开卡资源 ID(crd_<id>),事件体会带 activation_mode=auto_3ds 与 initial_pin,供商户把首个 PIN 展示给用户。

默认要会员自己的 L1。 人审一次即可:GET /v1/kyc 为 approved 之后,换 product_id 直接申请其他卡产品,不必再调 POST /v1/kyc/applications。若第二款的证件类型或开卡国家与这份已过审档案不匹配,开卡会直接报错,那是资格问题,不是要再做一次实名。

商户打开了快捷 KYC 时,没有真实 L1 的会员也可以开卡:系统从资料池独占绑一份已通过档案(首次 10 USDT),用那份资料向开卡行建用卡人。GET /v1/kyc 的 level 仍是 0,速汇继续拒。详见 快捷 KYC。

这与发卡「快捷申请」(库存盲发实体卡)不是同一件事。

开卡确认页:先拿报价


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

开卡费、这个地址的邮费、这个会员到底能不能申请 —— 一次问清。没有它,终端用户要等 POST /v1/cards/applications 扣完钱才第一次看见价钱。

⚠ issue_fee 与 shipping_fee 分开,别自己并成一个总价:闷在开卡费里的话,用户看到实体卡 20 USD 却不知道自己在为运费付钱;而「免费配送」这条卖点跟着 shipping_fee == 0 走,写死那句话等于承诺一件我方后台随时能改掉的事。

邮寄国家只影响邮费,不参与开卡国家限制。本人已有的邮寄地址均可选择,shipping_by_address 中 deliverable 为 true、reason 为空。产品国家黑白名单只检查本次使用的普通或快捷 KYC,虚拟卡与实体卡一致。

⚠ can_apply: false 时 reason 一起给:缺实名要引导去实名、card_address_required 要引导去添加邮寄地址、供应商不可用则显示「稍后再试」—— 三档处置完全不同,只显示一句「暂不可用」等于让用户卡在那儿。

实体卡

先决条件:会员名下必须已有一条邮寄地址

没有的话 POST /v1/cards/applications 直接拒 —— 卡是要寄出去的实体。


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

第一条地址自动成为默认,所以最短路径就是建一条然后直接下单。下单时可以带 address_id 指定寄到哪一条;不带就用默认那条。

⚠ 传了但我方解不出来的 address_id 当场拒,不会静默回落到默认地址 ——

这条线上的错寄是不可撤销的。

⚠ 地址在下单那一刻快照进订单行。之后会员改地址或删地址,

在途的包裹不会改道,历史订单的寄送地址也不会跟着变。

多两段:


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

下游库存实体卡审核通过后会自动进入 awaiting_bind(当面交付,不经过我方待发货)。平台自营仍走邮寄/面交人工履约。

步端点要点
绑卡POST /v1/cards/bind三要素(卡号后四位等),不需要强认证
激活POST /v1/cards/{id}/activate不可逆;OpenAPI 由商户自己完成验证后直调

下游商户在申请单进入 awaiting_bind 时会收到 card.application.awaiting_bind(库存模式标准申请审核通过后自动当面交付;平台自营则是线下面交确认,或邮寄标用户已签收)。收到后回查申请详情,再绑卡、激活。这不是开卡成功,不要展示卡已可用。平台自营会员不发这条事件。

⚠ 为什么绑卡不挂强认证:三要素本身就是占有权证明

(他手里有这张卡)。激活虽然不可逆,但 OpenAPI 不再把终端用户送去

我方托管页,而是由商户在自己域内完成验证后直调。

物流


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

四条状态轴(申请单 / 库存 / 物流 / 卡片)各自独立推进,任何一条都不由另一条派生。别按「物流已签收」推断「卡可用了」——会员还没激活。

相关端点