Z Zise Developers
卡发行 › 指南

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

开卡

虚拟卡


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

申请通过后发 card.application.approved

会员必须已经 L1 通过 —— 开卡用的就是他的 L1 资料。

开卡确认页:先拿报价


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

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

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

shipping_by_addressdeliverable: false 的地址请明确标出来并禁用支付,不要悄悄按 0 元邮费放行 —— 那会让用户付完钱才知道寄不到。

can_apply: falsereason 一起给:缺实名要引导去实名、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 当场拒,不会静默回落到默认地址 ——

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

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

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

多两段:


申请 ─► 制卡 ─► 邮寄 ─► 会员收到 ─► 绑卡 ─► 激活
端点要点
绑卡POST /v1/cards/bind三要素(卡号后四位等),不需要强认证
激活POST /v1/cards/{id}/activate需要强认证,且不可逆

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

(他手里有这张卡);而激活不可逆。

物流


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

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

相关端点