快速开始
接入步骤
选择请求域名
请使用与 ApiKey 所属环境一致的请求域名。
| 环境 | Base URL |
|---|---|
| Production | https://issuer.onerway.com/api/v1/merchant |
| Sandbox | https://sandbox-issuer.onerway.com/api/v1/merchant |
沙盒与生产环境的凭据相互独立。接口路径、请求方法和请求结构保持一致，但请求域名和
ApiKey 必须来自同一环境。创建沙盒商户账户
向 Onerway 提供邮箱、来源 IP 和事件接收 URL。沙盒账户创建后，请通过邮件链接登录商户后台，并获取用于接入和 webhook 验签的商户号与密钥。
提供来源 IP
调用发卡 API 前，请向 Onerway 提供稳定的服务端来源 IP，用于配置发卡访问白名单。
- 仅提交稳定的服务端来源 IP。
- 如果沙盒与生产环境使用不同来源 IP，请分别提供。
- 如果来源 IP 发生变更，请在切换流量前更新白名单。
安全保存凭据
发卡 API 通过 ApiKey 请求 Header 识别调用方权限。请在服务端保存 ApiKey、商户号和 webhook secret。
不要把发卡凭据暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。
配置事件回调
配置可接收卡操作和卡交易事件 webhook 的服务端回调地址。回调服务必须校验 x-signature，按 request_id 做事件去重，并在受理事件后返回 respCode=20000。
接入流程
| 步骤 | 动作 | 接口或来源 |
|---|---|---|
| 1 | 获取卡产品信息，并与 Onerway 确认 productId。 | Card product list |
| 2 | 创建与卡产品匹配的持卡人。 | 创建持卡人 |
| 3 | 使用 productId、cardholderId 和充值金额创建卡片。 | 创建卡片 |
| 4 | 按需查询卡片操作进度、基础信息、余额和敏感信息。 | 卡片查询 |
| 5 | 接收卡操作事件通知。 | 卡操作事件 |
| 6 | 查询卡交易记录，并接收交易事件通知。 | 查询交易记录 |