Z Zise Developers English
卡发行 › 指南

非平台自营商户统一接入流程:建会员、按产品绑定快捷资料、携带同一绑定报价与申请,由商户预付支付。

非自营商户:快捷 KYC 开卡

所有非平台自营的 merchant_hosted 商户,统一按本章接入快捷 KYC 开卡。虚拟卡与实体卡共用资料绑定和付款流程,出卡后的履约步骤按卡片类型分别处理。

标准顺序:建会员 → 选产品 → 绑定或复用快捷资料 → 携带绑定报价 → 商户付款申请 → 查询申请与卡片状态。

开通条件

本章是统一的商户接入流程,不表示接口会强制替换已提交的本人实名资料。报价与开卡必须显式传入所选 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。

不把“省略绑定后自动选择资料”作为标准接入方式:会员是否已有本人实名档案会影响自动选择。显式绑定能让 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。