> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 发卡 API 接入概览

> 列出虚拟卡（VCC）对外接口，并解答接入前的密钥准备、幂等、金额与时间格式、游标分页、显示卡号的方式、状态值和常见错误码。

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

## 接入前要准备什么？

1. 已开通虚拟卡服务，见[虚拟卡开通与协议](https://waffo.com/docs/zh/support/vcc-enablement-and-agreement-faq.md)。
2. 在商户 Portal「设置 → 集成」提交一把操作类型为 VCC 的公钥，审核通过后获得对应的 API key。VCC 类型与收款、代付、提现等类型互斥，只能单独选择，所以发卡接口要用一把单独的密钥。
3. 请求和响应的签名方式与其他 Waffo API 相同，见 [配置商户公钥](https://waffo.com/docs/zh/developer-docs/getting-started/public-key-configuration.md)。

## 有哪些接口？

| 分类 | 接口 | 路径 | 用途 |
| - | - | - | - |
| 账户 | 创建账户 | `/api/v1/issuing/accounts/create` | 按币种开设卡账户，开设期间状态为 `PROVISIONING` |
| 账户 | 查询账户 | `/api/v1/issuing/accounts/inquiry` | 查账户状态和余额构成 |
| 资金 | 充值 | `/api/v1/issuing/funding/topup` | 从结算余额充值到卡账户 |
| 资金 | 资金退回 | `/api/v1/issuing/funding/refund` | 申请把卡账户余额退回结算余额 |
| 资金 | 查询资金单 | `/api/v1/issuing/funding/inquiry` | 查单笔充值或退回的状态 |
| 资金 | 资金单列表 | `/api/v1/issuing/funding/list` | 分页查充值、退回记录 |
| 卡片 | 创建卡片 | `/api/v1/issuing/cards/create` | 开卡并设置限额 |
| 卡片 | 查询卡片详情 | `/api/v1/issuing/cards/inquiry` | 查卡片状态、限额和已用额度 |
| 卡片 | 卡片列表 | `/api/v1/issuing/cards/list` | 分页查卡片，可按状态、卡号后四位筛选 |
| 卡片 | 更新卡片 | `/api/v1/issuing/cards/update` | 改限额（`UPDATE_LIMITS`）、锁定（`FREEZE`）、解锁（`UNFREEZE`） |
| 卡片 | 注销卡片 | `/api/v1/issuing/cards/terminate` | 永久注销，不可撤销 |
| 卡片 | 生成卡片组件会话 | `/api/v1/issuing/cards/widget/generate` | 获取托管页地址，在你的页面中嵌入显示卡号 |
| 卡片 | 生成安全取数会话 | `/api/v1/issuing/cards/secret/generate` | 获取一次性取卡号的托管地址，用于你的系统自动填卡支付 |
| 交易 | 交易列表 | `/api/v1/issuing/transactions/list` | 分页查卡交易 |

接口详情见官网 API 参考，例如 [创建 VCC 卡片](https://waffo.com/docs/api-reference/issuing/card-create.md)、[VCC 账户充值](https://waffo.com/docs/api-reference/issuing/funding-topup.md)、[查询 VCC 交易列表](https://waffo.com/docs/api-reference/issuing/transaction-list.md)。对卡交易发起争议目前只能在 Portal 操作，见[对卡交易发起争议](https://waffo.com/docs/zh/support/vcc-card-disputes-faq.md)。

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

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

## 金额和时间怎么传？

| 项目 | 规则 |
| - | - |
| 金额 | 字符串，最多 12 位整数、2 位小数，不接受科学计数法和千分位 |
| 币种 | 须等于卡账户币种 |
| 时间 | ISO 8601 UTC；列表接口的 `startTime` 与 `endTime` 须同时传 |

## 列表接口怎么翻页？

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

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

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

不要自己存储完整卡号。两种方式：

| 方式 | 适合场景 | 说明 |
| - | - | - |
| 卡片组件会话 | 给你的用户在网页上查看卡号 | 返回托管页地址，在你的页面中嵌入。请求要带嵌入页的 Origin（https 加域名，不含路径和通配符）。地址含一次性凭证，按返回的有效期失效 |
| 安全取数会话 | 你的系统自动用卡号支付 | 返回一次性取数地址，只能从你登记的出口 IP 请求一次，按返回的有效期失效 |

卡号还没准备好时无法生成会话；已注销的卡也不能取卡号。

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

| 对象 | 状态值 |
| - | - |
| 卡账户 | `PROVISIONING`（开通中）、`ACTIVE`（正常）、`SUSPENDED`（已暂停） |
| 卡片 | `PENDING`（开卡处理中）、`ACTIVE`（已激活）、`LIMIT_REACHED`（已达限额）、`LOCKED`（已锁定）、`TERMINATED`（已关闭）、`EXPIRED`（已过期） |
| 资金单 | `PENDING`、`APPROVED`、`SUCCESS`、`REJECTED`，含义见[虚拟卡资金：充值、退回与余额构成](https://waffo.com/docs/zh/support/vcc-funding-and-balances-faq.md) |

各状态下能做哪些操作，见[卡片状态：锁定、解锁、注销与到期](https://waffo.com/docs/zh/support/vcc-card-status-faq.md)。

## 接口返回错误怎么排查？

接口错误码和通用处理方式见官网 [错误码速查](https://waffo.com/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes.md)。常见情况：

| 错误码 | 含义 |
| - | - |
| `A0003` | 参数不合法，例如 `cursor` 传了空字符串 |
| `A0201` | 账户标识不存在，或不属于你的商户 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.