发卡 API 接入概览

本页列出虚拟卡（VCC）对外接口，并说明接入前的密钥准备、幂等、分页等通用规则。每个接口的字段细节请看官网 API 参考。

​

接入前要准备什么？

1. 已开通虚拟卡服务，见虚拟卡开通与协议。
2. 在商户 Portal「设置 → 集成」提交一把操作类型为 VCC 的公钥，审核通过后获得对应的 API key。VCC 类型与收款、代付、提现等类型互斥，只能单独选择，所以发卡接口要用一把单独的密钥。
3. 请求和响应的签名方式与其他 Waffo API 相同，见 配置商户公钥。

​

有哪些接口？

接口详情见官网 API 参考，例如 创建 VCC 卡片、VCC 账户充值、查询 VCC 交易列表。对卡交易发起争议目前只能在 Portal 操作，见对卡交易发起争议。

​

怎么避免重复开卡、重复充值？

创建账户、充值、资金退回、创建卡片都要求传 idempotentId 作为业务键，1–64 位字母、数字、下划线或横线。超时或网络错误重试时，请复用同一个 idempotentId，不会重复执行。每笔新业务使用新的业务键。

​

金额和时间怎么传？

​

列表接口怎么翻页？

卡片列表、资金单列表、交易列表都用游标分页：

• 首次请求不传 cursor；pageSize 取 1–100，默认 10。
• 响应中 hasMore 为 true 时，用返回的 nextCursor 请求下一批；hasMore 为 false 时 nextCursor 为空。
• cursor 传空字符串会返回 A0003。

​

怎么在我的页面上显示卡号？

不要自己存储完整卡号。两种方式： 卡号还没准备好时无法生成会话；已注销的卡也不能取卡号。

​

账户和卡片状态在接口里怎么表示？

各状态下能做哪些操作，见卡片状态：锁定、解锁、注销与到期。

​

接口返回错误怎么排查？

接口错误码和通用处理方式见官网 错误码速查。常见情况：