跳转到主要内容

​
核心对接流程

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

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

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

​
流程步骤

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

​
相关接口

接口方法路径说明
获取 TokenGET/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-注销）
设置 PINPOST/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消费
AtmATM 提现
Manage_fee管理费
Refund退款
Reversal撤销/拒付
Open_card开卡费

​
授权模式特殊流程

授权模式需要实时授权确认 
用户消费请求
    ↓
[Webhook Auth 通知] 平台发送授权通知
    ↓
商户需在 800 ms内确认
    ↓
返回应答 { "code": 0 }
    ↓
授权通过 → 交易继续 ✓
    或
授权拒绝 → 交易失败 ✗
    ↓
[Webhook 消费通知] 最终结果通知
重要提示：授权模式对响应性能要求很高，需要确保系统能在 800 ms内完成授权应答。

​
完整对接时间线

阶段操作预计时间
准备阶段申请凭证、配置白名单、配置回调1-2 天
认证阶段集成 SumSub、完成 KYC3-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：费用明细在开卡时的套餐配置中，包含消费费率、手续费、外汇费等。具体见「常量表」章节。