业务流程说明

核心对接流程

完整的支付卡服务对接分为四个阶段，从用户认证到消费对账。以下为各阶段的详细说明和对应接口：

阶段 1：用户注册与 KYC 认证

场景说明：完成持卡人认证，持卡人需要认证后才能开卡。

流程步骤

前端集成 SumSub KYC 组件 —— 用户完成身份验证
发起持卡人认证 —— 调用接口创建持卡人并发起认证
查询认证状态 —— 获取持卡人列表或详情，确认认证是否通过

接口	方法	路径	说明
获取 Token	GET	`/open-api/v1/merchant/token`	获取 Access-Token，所有后续请求都需要
持卡人认证申请	POST	`/open-api/v1/cardholder/apply`	通过这个接口完成持卡人创建和认证；持卡人认证失败后，可以通过该接口完成认证信息更新和重新发起认证
获取持卡人列表	POST	`/open-api/v1/cardholder/list`	获取当前持卡人的列表
获取持卡人详细信息	GET	`/open-api/v1/cardholder/{cardholder_no}/info`	获取持卡人的卡片列表；可用于验证认证状态

典型流程

前端KYC认证 
    ↓
[POST /cardholder/apply] 发起持卡人申请
    ↓
认证中... (平台与Sumsub验证)
    ↓
[POST /cardholder/list] 查询持卡人状态
    ↓
认证成功 ✓ (状态: Approved)

认证状态说明

状态	说明
Pending	待认证
In_progress	认证中
Approved	认证成功 ✓（可以开卡）
Rejected	认证失败（可重新申请）

阶段 2：选套餐、开卡、卡管理

场景说明：持卡人认证通过后，用户选择卡类型（虚拟卡/实体卡）、开卡并进行卡片管理。

流程步骤

获取卡套餐或 BIN 列表 —— 根据对接模式获取可用的卡产品
申请开卡 —— 用户选择卡类型（虚拟/实体）并提交开卡申请
查询卡状态 —— 获取卡列表或卡详情，确认开卡是否成功
激活卡（实体卡） —— 用户收到实体卡后，需激活才能使用
管理卡状态 —— 冻结、解冻、注销卡片

接口	方法	路径	模式	说明
获取卡套餐列表	POST	`/open-api/v1/card/package/list`	授信	需要登录商户后台，完成卡套餐创建；开卡时，根据对应套餐进行收费
支持的卡 BIN 列表	POST	`/open-api/v1/card/support/bins`	授权	获取授权模式支持的卡 BIN，卡的收费需要商户自己维护
开卡申请	POST	`/open-api/v1/card/apply`	通用	开通一张卡片（授信传 `package_no`，授权传 `card_bin_no`）
获取卡列表	POST	`/open-api/v1/card/list`	通用	获取当前卡片列表
获取卡详情	GET	`/open-api/v1/card/{card_no}/detail`	通用	获取卡片详细信息（包括费率、手续费等）
获取卡隐私信息	GET	`/open-api/v1/card/{card_no}/private/info`	通用	获取卡片的 CVV、有效期、卡号等关键交易信息（需联系商务开通 PCI 权限）
实体卡激活	POST	`/open-api/v1/card/active`	通用	实体卡需要拿到卡片后，激活使用（需上传加密的 CVV）
修改卡状态	POST	`/open-api/v1/card/status/update`	通用	修改卡片的使用状态（Frozen-冻结 / Activated-启用 / Delete-注销）
设置 PIN	POST	`/open-api/v1/card/pin/set`	通用	设置实体卡 PIN（需上传加密的 PIN）
卡变动通知	—	Webhook	通用	持卡人申请开卡后，卡片状态变动会发送通知；由于风控等行为导致卡片变动时，也会收到通知

典型流程

授信模式：

[POST /card/package/list] 获取套餐列表
    ↓
用户选择套餐
    ↓
[POST /card/apply] 申请开卡 (传 package_no)
    ↓
[POST /card/list] 查询卡状态
    ↓
虚拟卡：立即可用 ✓
    或
实体卡：邮寄中 → 用户收到卡 → [POST /card/active] 激活
    ↓
[POST /card/pin/set] 设置 PIN (可选)

授权模式：

[POST /card/support/bins] 获取支持的 BIN
    ↓
用户选择卡 BIN
    ↓
[POST /card/apply] 申请开卡 (传 card_bin_no)
    ↓
[POST /card/list] 查询卡状态
    ↓
虚拟卡：立即可用 ✓
    或
实体卡：邮寄中 → 用户收到卡 → [POST /card/active] 激活

卡片状态说明

状态	说明	可进行操作
Pending	进行中（制卡中等）	—
ToActivate	待激活（实体卡收到后）	激活、修改状态
Activated	已激活/正常	消费、冻结、注销、设置 PIN
Frozen	已冻结	解冻、注销
Delete	已删除/注销	—
Fail	失败	重新申请

阶段 3：账户与资金管理（授信模式）

场景说明：持卡人账户余额查看，资金划转。仅授信模式支持。

流程步骤

充值备付金 —— 商户在后台手动充值备付金（暂无接口）
查询账户余额 —— 获取持卡人账户信息，确认可用资产
执行资金划转 —— 用户充值或提现时，进行资金划转
查询划转流水 —— 对账时查看划转历史记录

接口	方法	路径	说明
备付金充值	—	—	目前没开放接口，需要手动在商户后台完成充值
持卡人金额划转	POST	`/open-api/v1/account/transfer`	在持卡人资金有变动时（充值或提现），需要同步进行资金划转，保持两边资金一致；固定币种 TUSDT
获取持卡人账户信息列表	GET	`/open-api/v1/account/{cardholder_no}/info`	持卡人授信模式下，账户的可用资产
获取账户交易流水列表	POST	`/open-api/v1/account/transfer/list`	持卡人资金的划转历史

典型流程

用户充值请求
    ↓
[POST /account/transfer] 执行划转 (type: In)
    ↓
划转成功 ✓ (返回划转单号)
    ↓
[GET /account/{cardholder_no}/info] 查询余额确认
    ↓
[POST /account/transfer/list] 查询划转流水对账

划转类型

类型	方向	说明
In	公司 → 持卡人	用户充值（允许商户账户为负）
Out	持卡人 → 公司	用户提现（需充足余额，否则失败）

阶段 4：消费与账单

场景说明：用户用卡消费后，查看交易记录、交易详情，商户进行对账。

流程步骤

用户消费 —— 持卡人使用卡片进行消费交易
接收消费通知 —— 平台通过 Webhook 发送消费订单通知
查询消费详情 —— 根据消费单号获取详细信息
查询消费列表 —— 按时间范围查询消费记录，用于对账

接口	方法	路径	说明
消费订单通知	—	Webhook	持卡人发生消费时，会发送通知；订单结算时也会进行消费通知；包含费用明细、商户信息等
获取卡消费记录列表	POST	`/open-api/v1/card/consume/list`	针对卡维度，查询历史消费记录；支持按时间范围、卡号等筛选
获取卡消费详情	GET	`/open-api/v1/card/consume/{consume_no}/info`	查询订单消费详细信息，包含费率、手续费、商户信息等

典型流程

用户使用卡片消费
    ↓
[Webhook 消费通知] 平台发送消费订单通知
    ↓
商户处理通知 (返回 code: 0)
    ↓
[GET /consume/{consume_no}/info] 查询消费详情
    ↓
[POST /consume/list] 定期查询消费列表对账
    ↓
生成账单和对账单

消费类型

类型	说明
Consumption	消费
Atm	ATM 提现
Manage_fee	管理费
Refund	退款
Reversal	撤销/拒付
Open_card	开卡费

授权模式特殊流程

授权模式需要实时授权确认

用户消费请求
    ↓
[Webhook Auth 通知] 平台发送授权通知
    ↓
商户需在 800 ms内确认
    ↓
返回应答 { "code": 0 }
    ↓
授权通过 → 交易继续 ✓
    或
授权拒绝 → 交易失败 ✗
    ↓
[Webhook 消费通知] 最终结果通知

重要提示：授权模式对响应性能要求很高，需要确保系统能在 800 ms内完成授权应答。

完整对接时间线

阶段	操作	预计时间
准备阶段	申请凭证、配置白名单、配置回调	1-2 天
认证阶段	集成 SumSub、完成 KYC	3-5 天
开卡阶段	开卡接口对接、测试虚拟卡+实体卡	5-7 天
账户阶段	完成账户和划转接口对接（授信模式）	3-5 天
消费阶段	接收和处理 Webhook 通知、消费查询	3-5 天
测试阶段	全链路测试、上线前审查	2-3 天
总计		15-25 天

常见问题

Q1：用户必须完成 KYC 才能开卡吗？
A：是的，持卡人必须完成 KYC 认证，状态为 Approved 才能进行开卡操作。 Q2：开卡后多久可以使用？
A：虚拟卡申请后立即可用；实体卡需要用户收到卡片后激活。 Q3：怎么区分授信模式和授权模式？
A：根据对接前商务确认的 integration_mode 决定：

CREDIT_EXTENSION = 授信模式
AUTHORIZATION = 授权模式

Q4：授权模式为什么要 800 毫秒内确认？
A：授权模式实时扣款，需要商户在 800 毫秒内确认是否允许交易，保证交易流畅性。超时会默认为拒绝交易 Q5：消费费用怎么计算？
A：费用明细在开卡时的套餐配置中，包含消费费率、手续费、外汇费等。具体见「常量表」章节。

接入指引

API文档

附录

核心对接流程

阶段 1：用户注册与 KYC 认证

流程步骤

相关接口

典型流程

认证状态说明

阶段 2：选套餐、开卡、卡管理

流程步骤

相关接口

典型流程

卡片状态说明

阶段 3：账户与资金管理（授信模式）

流程步骤

相关接口

典型流程

划转类型

阶段 4：消费与账单

流程步骤

相关接口

典型流程

消费类型

授权模式特殊流程

完整对接时间线

常见问题

​核心对接流程

​阶段 1：用户注册与 KYC 认证

​流程步骤

​相关接口

​典型流程

​认证状态说明

​阶段 2：选套餐、开卡、卡管理

​流程步骤

​相关接口

​典型流程

​卡片状态说明

​阶段 3：账户与资金管理（授信模式）

​流程步骤

​相关接口

​典型流程

​划转类型

​阶段 4：消费与账单

​流程步骤

​相关接口

​典型流程

​消费类型

​授权模式特殊流程

​完整对接时间线

​常见问题

核心对接流程

阶段 1：用户注册与 KYC 认证

流程步骤

相关接口

典型流程

认证状态说明

阶段 2：选套餐、开卡、卡管理

流程步骤

相关接口

典型流程

卡片状态说明

阶段 3：账户与资金管理（授信模式）

流程步骤

相关接口

典型流程

划转类型

阶段 4：消费与账单

流程步骤

相关接口

典型流程

消费类型

授权模式特殊流程

完整对接时间线

常见问题