申请 → 审核 → 开卡。实体卡多绑卡与激活两步,且激活不可逆。
开卡
非平台自营商户统一入口:快捷 KYC 开卡流程。merchant_hosted 商户按产品绑定快捷资料,报价与申请显式传同一绑定,并使用 funding_source: merchant。
虚拟卡
POST /v1/cards/applications { "product_id": "…", "source_asset": "USDT", "funding_source": "merchant" }
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 展示给用户。
卡详情 GET /v1/cards/{id} 的 auto_activation 表示是否由平台自动激活。为 true 时,绑定完成后等待激活结果,无需用户再次提交激活或设置 PIN;激活码先到或后到都由平台衔接处理。绑定受理、card.bound 和 card.3ds.received均不代表激活成功,客户端只有查询到卡状态为 active 后才应展示成功。
平台自营的普通实名开卡流程默认要会员自己的 L1。 人审一次即可:GET /v1/kyc 为 approved 之后,换 product_id 直接申请其他卡产品,不必再调 POST /v1/kyc/applications。若第二款的证件类型或开卡国家与这份已过审档案不匹配,开卡会直接报错,那是资格问题,不是要再做一次实名。
商户打开了快捷 KYC 时,没有真实 L1 的会员也可以开卡:系统从资料池独占绑一份已通过档案(资料费按商户配置计收),用那份资料向开卡行建用卡人。GET /v1/kyc 的 level 仍是 0,速汇继续拒。详见 快捷 KYC。
这与发卡「快捷申请」(库存盲发实体卡)不是同一件事。
开卡确认页:先拿报价
GET /v1/cards/products/{id}/quote
开卡费、这个地址的邮费、这个会员到底能不能申请 —— 一次问清。没有它,终端用户要等 POST /v1/cards/applications 扣完钱才第一次看见价钱。
返回的 min_first_topup 是这一款卡的首充下限,人读金额,与 issue_fee 同一套。下单时把它原样放进 first_topup。低于它会 400 amount_out_of_range,申请单不会创建。"0.00" 表示没有首充下限,可以不传 first_topup。
⚠ issue_fee 与 shipping_fee 分开,别自己并成一个总价:闷在开卡费里的话,用户看到实体卡 20 USD 却不知道自己在为运费付钱;而「免费配送」这条卖点跟着 shipping_fee == 0 走,写死那句话等于承诺一件我方后台随时能改掉的事。
邮寄国家只影响邮费,不参与开卡国家限制。本人已有的邮寄地址均可选择,shipping_by_address 中 deliverable 为 true、reason 为空。产品国家黑白名单只检查本次使用的普通或快捷 KYC,虚拟卡与实体卡一致。
⚠ can_apply: false 时 reason 一起给:缺实名要引导去实名、card_address_required 要引导去添加邮寄地址、供应商不可用则显示「稍后再试」—— 三档处置完全不同,只显示一句「暂不可用」等于让用户卡在那儿。
实体卡
平台自营的邮寄地址要求
平台自营的实体卡流程要求会员名下已有一条邮寄地址;缺少地址时申请会被拒绝。非自营 merchant_hosted 商户自行履约,不要求先在我方建立邮寄地址,按非自营快捷 KYC 流程申请并继续绑卡、激活。
以下地址簿步骤适用于需要我方邮寄地址的流程:
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 | 先绑卡,拿到 card.bound 里的 crd_ 再调。有效期 + PIN,不可逆。PIN 位数按卡产品,有的实体卡要 6 位数字 |
下游商户在申请单进入 awaiting_bind 时会收到 card.application.awaiting_bind(库存模式标准申请审核通过后自动当面交付;平台自营则是线下面交确认,或邮寄标用户已签收)。收到后回查申请详情,再绑卡、激活。这不是开卡成功,不要展示卡已可用。平台自营会员不发这条事件。
绑定收尾、卡行建成后会再发 card.bound。data.id 是公开卡资源 ID(crd_<id>),状态为 unactivated。有申请单时带 application_id(cap_<id>)。拿它回查 GET /v1/cards/{id},再激活。这不是激活成功。平台自营会员不发。
⚠ 为什么绑卡不挂强认证:三要素本身就是占有权证明
(他手里有这张卡)。激活虽然不可逆,但 OpenAPI 不再把终端用户送去
我方托管页,而是由商户在自己域内完成验证后直调。
物流
GET /v1/cards/applications/{id}/shipment
四条状态轴(申请单 / 库存 / 物流 / 卡片)各自独立推进,任何一条都不由另一条派生。别按「物流已签收」推断「卡可用了」——会员还没激活。