申请 → 审核 → 开卡。实体卡多绑卡与激活两步,且激活不可逆。
开卡
虚拟卡
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
四条状态轴(申请单 / 库存 / 物流 / 卡片)各自独立推进,任何一条都不由另一条派生。别按「物流已签收」推断「卡可用了」——会员还没激活。