Consumer API 接入指南

本指南介绍从创建 API Key 到完成首次接口调用的接入流程。

接入顺序：创建 API Key → 保存密钥 → 配置接入程序 → 启用 API Key → 发起首次调用。

1. 创建 API Key

进入开发者中心，点击「创建 API Key」。

填写名称、允许访问的 IP，选择接口权限。

选择密钥方式，按下表完成设置。

确认信息，完成安全验证。

方式	操作及私钥来源
自动生成密钥	平台生成密钥，创建成功后下载并妥善保存密钥文件。
手动上传公钥	上传客户端鉴权公钥和客户端加密公钥，配对私钥由接入方自行保管。平台不提供这些私钥。

生产环境 Base URL

https://api.wayflow.tech

联调环境使用平台分配的地址。

准备以下配置：

首次只读调用需要前四项；涉及加解密时，再配置相应密钥。私钥来源见上方创建方式。

平台公钥及所需指纹从开发者中心获取。

Webhook 另需配置接收方 API Key 业务 ID，不要与调用凭证或公钥指纹混用。两套客户端私钥分开保管，仅在服务端使用。

在运行示例的终端设置：

MERCHANT_* 是示例变量名，对应客户端私钥；示例通过文件路径读取 PEM 内容。

SDK 是平台提供的服务端开发工具，负责请求签名、响应验签，并提供加解密能力。获取指定版本的 SDK 源码交付包，按包内安装说明接入项目，并固定交付版本及依赖。

只需选择一种语言：

完成所选语言的安装和配置后，按下一节启用 API Key，再运行示例。

配置完成后，在开发者中心启用该 API Key。

运行所选语言的示例，发起第一次只读调用：

{"page": 0, "size": 20}

成功条件：响应验签通过、HTTP 2xx、业务响应 success=true。SDK 通常直接返回业务 data；各语言示例注明了取值方式。

失败时保存 HTTP 状态、错误码及请求 ID，按错误码与重试排查。不要关闭验签，也不要记录私钥、完整凭证或敏感数据。

操作	关联步骤
查询产品与钱包	产品组 ID 可从卡产品组列表获取
发卡	建议先调用发卡预检；发卡使用加密请求及幂等键
查询发卡结果	单张、多张均返回批次 ID，用于查询发卡任务详情及明细
接收通知	登记 HTTPS 回调地址、接收方 API Key 和订阅事件类型

写操作的幂等键由业务系统生成并保存。同一业务重试复用原幂等键及相同业务内容，每次发送重新生成签名所需的时间戳和 nonce。