申请 → 审核 → 开卡。实体卡多绑卡与激活两步,且激活不可逆。
开卡
虚拟卡
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_fee 与 shipping_fee 分开,别自己并成一个总价:闷在开卡费里的话,用户看到实体卡 20 USD 却不知道自己在为运费付钱;而「免费配送」这条卖点跟着 shipping_fee == 0 走,写死那句话等于承诺一件我方后台随时能改掉的事。
⚠ shipping_by_address 里 deliverable: false 的地址请明确标出来并禁用支付,不要悄悄按 0 元邮费放行 —— 那会让用户付完钱才知道寄不到。
⚠ 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当场拒,不会静默回落到默认地址 ——这条线上的错寄是不可撤销的。
⚠ 地址在下单那一刻快照进订单行。之后会员改地址或删地址,
在途的包裹不会改道,历史订单的寄送地址也不会跟着变。
多两段:
申请 ─► 制卡 ─► 邮寄 ─► 会员收到 ─► 绑卡 ─► 激活
| 步 | 端点 | 要点 |
|---|---|---|
| 绑卡 | POST /v1/cards/bind | 三要素(卡号后四位等),不需要强认证 |
| 激活 | POST /v1/cards/{id}/activate | 需要强认证,且不可逆 |
⚠ 为什么绑卡不挂强认证而激活挂:三要素本身就是占有权证明
(他手里有这张卡);而激活不可逆。
物流
GET /v1/cards/applications/{id}/shipment
四条状态轴(申请单 / 库存 / 物流 / 卡片)各自独立推进,任何一条都不由另一条派生。别按「物流已签收」推断「卡可用了」——会员还没激活。