> ## Documentation Index > Fetch the complete documentation index at: https://docs-payment-merchant.keysecure.io/llms.txt > Use this file to discover all available pages before exploring further. # 业务流程说明 ## 核心对接流程 完整的支付卡服务对接分为四个阶段，从用户认证到消费对账。以下为各阶段的详细说明和对应接口： *** ## 阶段 1：用户注册与 KYC 认证 **场景说明**：完成持卡人认证，持卡人需要认证后才能开卡。 ### 流程步骤 1. **前端集成 SumSub KYC 组件** —— 用户完成身份验证 2. **发起持卡人认证** —— 调用接口创建持卡人并发起认证 3. **查询认证状态** —— 获取持卡人列表或详情，确认认证是否通过 ### 相关接口 | 接口 | 方法 | 路径 | 说明 | | ----------- | ---- | ---------------------------------------------- | ------------------------------------------------ | | 获取 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：选套餐、开卡、卡管理 **场景说明**：持卡人认证通过后，用户选择卡类型（虚拟卡/实体卡）、开卡并进行卡片管理。 ### 流程步骤 1. **获取卡套餐或 BIN 列表** —— 根据对接模式获取可用的卡产品 2. **申请开卡** —— 用户选择卡类型（虚拟/实体）并提交开卡申请 3. **查询卡状态** —— 获取卡列表或卡详情，确认开卡是否成功 4. **激活卡（实体卡）** —— 用户收到实体卡后，需激活才能使用 5. **管理卡状态** —— 冻结、解冻、注销卡片 ### 相关接口 | 接口 | 方法 | 路径 | 模式 | 说明 | | ----------- | ---- | ------------------------------------------ | -- | ----------------------------------------------- | | 获取卡套餐列表 | 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：账户与资金管理（授信模式） **场景说明**：持卡人账户余额查看，资金划转。仅授信模式支持。 ### 流程步骤 1. **充值备付金** —— 商户在后台手动充值备付金（暂无接口） 2. **查询账户余额** —— 获取持卡人账户信息，确认可用资产 3. **执行资金划转** —— 用户充值或提现时，进行资金划转 4. **查询划转流水** —— 对账时查看划转历史记录 ### 相关接口 | 接口 | 方法 | 路径 | 说明 | | ----------- | ---- | ------------------------------------------- | ------------------------------------------------ | | 备付金充值 | — | — | 目前没开放接口，需要手动在商户后台完成充值 | | **持卡人金额划转** | 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：消费与账单 **场景说明**：用户用卡消费后，查看交易记录、交易详情，商户进行对账。 ### 流程步骤 1. **用户消费** —— 持卡人使用卡片进行消费交易 2. **接收消费通知** —— 平台通过 Webhook 发送消费订单通知 3. **查询消费详情** —— 根据消费单号获取详细信息 4. **查询消费列表** —— 按时间范围查询消费记录，用于对账 ### 相关接口 | 接口 | 方法 | 路径 | 说明 | | ---------- | ---- | --------------------------------------------- | ----------------------------------------- | | **消费订单通知** | — | 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：费用明细在开卡时的套餐配置中，包含消费费率、手续费、外汇费等。具体见「常量表」章节。