非平台自营商户统一接入流程:建会员、按产品绑定快捷资料、携带同一绑定报价与申请,由商户预付支付。
非自营商户:快捷 KYC 开卡
所有非平台自营的 merchant_hosted 商户,统一按本章接入快捷 KYC 开卡。虚拟卡与实体卡共用资料绑定和付款流程,出卡后的履约步骤按卡片类型分别处理。
标准顺序:建会员 → 选产品 → 绑定或复用快捷资料 → 携带绑定报价 → 商户付款申请 → 查询申请与卡片状态。
开通条件
- 商户已开通卡业务、快捷 KYC 和目标卡产品;商户预付余额足以支付资料费、开卡成本及首充。功能未开通时先联系平台开通,建会员不会自动开通这些权限。
- API Key 具备
members:write、kyc:read、kyc:write、cards:read、cards:write。先按鉴权与签名取得令牌并签名。 - 代会员的请求始终使用同一商户凭据及同一
x-on-behalf-of,值为该商户自己的external_member_id或返回的mem_…。不要使用其他商户的产品、会员或绑定 ID。 - 每个独立 POST 操作使用不同的 UUID v4
x-idempotency-key。原操作遇到网络超时或结果未知时,保留原请求体、原幂等键回查或重试。
本章是统一的商户接入流程,不表示接口会强制替换已提交的本人实名资料。报价与开卡必须显式传入所选 quick_kyc_binding_id,才能明确指定本次使用快捷资料。
第一步:建立会员
调用 POST /v1/members:
{
"external_member_id": "member-10086",
"email": "member10086@example.com"
}
保存返回的会员 id;后续代会员请求使用 x-on-behalf-of: member-10086,或使用返回的 mem_…。这个外部会员号由你自己的系统确定,不需要加其他商户的前缀。
建档成功只表示会员已存在,不表示已通过本人 KYC。走快捷资料开卡无需先提交本人 L1;已经有本人 L1 / L2 的会员也可以使用本章流程,原实名档案和等级保持不变。
第二步:选定卡产品
调用 GET /v1/cards/products,从当前商户可见的产品中选择支持快捷资料的目标产品,保存返回的 id,后续始终使用这个 cpd_…。要求 L2 的产品不适用本流程,须在分配收费前排除。
产品 ID、费用、支持的扣款资产和首充下限都以当前接口及配置为准。不要照抄其他商户的产品 ID,也不要仅凭 BIN 判断虚拟卡或实体卡。
第三步:按产品绑定或复用快捷资料
可先用 GET /v1/kyc/quick 查看当前会员的有效绑定。随后调用 POST /v1/kyc/quick,按目标产品选择匹配资料:
{
"card_product_id": "cpd_42",
"email": "member10086+card01@example.com"
}
cpd_42 仅为示例,必须替换为第二步拿到的产品 ID。email 应是你或会员可接收通知的邮箱;新分配要求完整邮箱未被任何普通 KYC、快捷资料或历史档案使用过。会员建档邮箱与 KYC 邮箱是不同用途,不能以建档成功推断该邮箱符合快捷资料分配要求。
建议邮箱总长度不超过 50 字符。邮箱比较忽略大小写及首尾空格,保留 +card01;使用别名前应确认邮箱服务确实支持接收。
| 响应 | 含义 | 处理 |
|---|---|---|
200,reused: true | 复用已有匹配绑定,不再收资料费 | 保存返回的 binding.id |
201,reused: false | 新绑定,已收取本次资料费 | 保存返回的 binding.id |
已有匹配绑定会优先复用,无需新邮箱,也不会修改已绑定邮箱。每名会员最多 5 份有效绑定。这个接口的 201 表示资料已绑定,不表示卡已申请或开出。
资料费按商户已配置费率从商户预付支付;不要把平台默认资料费或其他商户费率写死到程序。此绑定接口无需传 funding_source,服务端根据商户模式处理扣款。
第四步:用同一绑定报价
调用 GET /v1/cards/products/{id}/quote,把第三步的 binding.id 放入查询参数:
GET /v1/cards/products/{id}/quote?quick_kyc_binding_id=7c9e6679-7425-40de-944b-e07fc1f90ae7
将 {id} 换为第二步产品 ID。检查 can_apply、reason、费用、扣款资产及 min_first_topup;can_apply: false 时先处理原因,不能继续盲目申请。报价不扣费,也不保证提交时余额和产品状态不变。
不要用会员本人的 KYC 报价,再换快捷资料申请;报价与申请必须使用同一绑定。 地区规则按本次所选资料的地址国家判断,地址国家缺失时使用国籍;证件签发国家是单独字段,不能与两者混用。要求 L2 的产品不支持本章的快捷绑定申请;即使会员本人已有 L2,显式传快捷绑定仍会被拒绝。请选择支持快捷资料的产品;必须申请 L2 产品时,另按本人实名流程接入。
第五步:从商户预付申请开卡
调用 POST /v1/cards/applications:
{
"product_id": "cpd_42",
"quick_kyc_binding_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"source_asset": "USDT",
"first_topup": "5",
"funding_source": "merchant",
"client_key": "member-10086-card-order-001"
}
产品、绑定、资产与首充金额均须替换为前面步骤确认的值;示例中的 5 不是所有产品的固定首充额。first_topup 不得低于 min_first_topup。
funding_source必须显式为merchant。省略或传member返回invalid_fields;非自营商户使用商户实际预付,不通过会员钱包入金来付款。- 提供
product_id后,卡片类型由产品确定,可省略form_factor。若显式传入,申请参数使用virtual或physical,必须与产品一致;部分查询响应使用virtual_card/physical_card,不要原样复制为申请参数。 client_key是你方这笔开卡订单的稳定业务键。网络重试保留该键,不要生成另一笔订单;修改产品重新下单时才使用新业务键。- 开卡费、首充与快捷资料费分别处理。已绑定资料的后续开卡不重复收取资料费,但新开卡仍按产品规则计费。
不把“省略绑定后自动选择资料”作为标准接入方式:会员是否已有本人实名档案会影响自动选择。显式绑定能让 L0、L1、L2 会员使用同一套调用流程。
第六步:按申请与卡片状态完成流程
保存返回的申请 id(cap_…),通过 GET /v1/cards/applications/{id} 回查。处理开卡事件时先验签、按事件去重,再回查最新状态。
开卡申请返回 201 只代表受理,不代表卡已可用。 不要在收到 HTTP 成功响应后再次创建订单,也不要把所有状态都当作等待 issued。
| 卡片类型 | 后续步骤 |
|---|---|
| 虚拟卡 | 等待申请出卡结果,取得 card_id 后调用 GET /v1/cards/{id} 确认卡片状态;有首充时另外确认充值结果 |
| 实体卡 | 按产品履约;库存模式进入 awaiting_bind 后调用 POST /v1/cards/bind,取得卡 ID 后按产品要求激活并回查卡状态 |
merchant_hosted 实体卡由商户自行履约,不要求先在我方创建邮寄地址。平台自营的邮寄地址要求不套用到这条流程。实体卡申请可能停在 pending_activation,应继续处理卡片激活,不能一直等待申请变成 issued。详见实体卡绑定与激活。
异常、重试与资料费
| 错误或事件 | 处理 |
|---|---|
quick_kyc_disabled | 联系平台为当前商户开通快捷 KYC |
quick_kyc_unpaid | 检查商户预付、卡业务开关及资金限制;解决后再提交 |
quick_kyc_exhausted | 当前无匹配资料;联系平台处理,避免循环申请 |
quick_kyc_limit | 已达到有效绑定数量上限,先检查现有绑定 |
request_rejected 且错误字段指向 email | 邮箱已使用,换符合要求的新邮箱;其他拒绝原因不能一概归为邮箱问题 |
card_country_not_supported | 所选资料地区不符合产品要求,重新选择相容产品或资料;本人 KYC 通过不等于满足该产品地区规则 |
product_not_available | 核对本商户产品授权、产品启用状态、资产及卡片类型,保留 request_id 联系平台 |
invalid_fields | 按返回的字段修正,例如 email、funding_source 或无效的绑定 |
kyc.quick.compensated | 绑定已补偿失效,资料费已退;重新查询有效绑定并按第三步处理 |
明确的 4xx 错误修正后重新提交,使用新的请求幂等键;原键可能仍返回缓存的失败。网络超时、5xx 或结果未知时保留原键,按幂等与重试处理,防止重复下单。
开卡失败不等于快捷资料费必然退款。符合首次使用失败补偿条件、且不存在成功受理证据、已出卡或在途申请时,可由平台按补偿流程处理。以 kyc.quick.compensated 通知和实际账务为准;有效绑定可用于相容产品,已补偿绑定不可继续使用。开卡费及首充结果分别回查,不能从资料费退款推断整笔申请全部退款。
本人认证等级与其他业务
快捷绑定只用于符合条件的卡产品,不建立或覆盖会员本人实名档案,也不提升 GET /v1/kyc 的 level。仅有快捷绑定的 L0 会员仍为 L0;不得把它作为本人 L1 / L2 已通过的依据。
速汇等其他业务按各自要求完成本人认证。平台自营的本人认证和会员付款流程,参见 KYC 概览;快捷资料字段与绑定规则参见快捷 KYC。