# 接入准备

> 调用发卡 API 前，请仔细阅读下面流程。

## 接入步骤

<steps level="3">

### 选择请求域名

请使用与 `ApiKey` 所属环境一致的请求域名。

| 环境 | Base URL |
| --- | --- |
| Production | `https://issuer.onerway.com/api/v1/merchant` |
| Sandbox | `https://sandbox-issuer.onerway.com/api/v1/merchant` |

<note>

沙盒与生产环境的凭据相互独立。接口路径、请求方法和请求结构保持一致，但请求域名和 `ApiKey` 必须来自同一环境。

</note>

### 创建沙盒商户账户

向 Onerway 提供邮箱、来源 IP 和事件接收 URL。沙盒账户创建后，请通过邮件链接登录商户后台，并获取用于接入和 webhook 验签的商户号与密钥。

### 提供来源 IP

调用发卡 API 前，请向 Onerway 提供稳定的服务端来源 IP，用于配置发卡访问白名单。

- 仅提交稳定的服务端来源 IP。
- 如果沙盒与生产环境使用不同来源 IP，请分别提供。
- 如果来源 IP 发生变更，请在切换流量前更新白名单。

### 安全保存凭据

发卡 API 通过 `ApiKey` 请求 Header 识别调用方权限。请在服务端保存 `ApiKey`、商户号和 webhook secret。

<warning>

不要把发卡凭据暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。

</warning>

### 配置事件回调

配置可接收卡操作和卡交易事件 webhook 的服务端回调地址。回调服务必须校验 `x-signature`，按 `request_id` 做事件去重，并在受理事件后返回 `respCode=20000`。

</steps>

## 接入流程

| 步骤 | 动作 | 接口或来源 |
| --- | --- | --- |
| 1 | 获取卡产品信息，并与 Onerway 确认 `productId`。 | Card product list |
| 2 | 创建与卡产品匹配的持卡人。 | [创建持卡人](/zh/issuing/api-reference/endpoints/create-cardholder) |
| 3 | 使用 `productId`、`cardholderId` 和充值金额创建卡片。 | [创建卡片](/zh/issuing/api-reference/endpoints/create-card) |
| 4 | 按需查询卡片操作进度、基础信息、余额和敏感信息。 | [卡片查询](/zh/issuing/api-reference/endpoints/get-operate-record-list) |
| 5 | 接收卡操作事件通知。 | [卡操作事件](/zh/issuing/api-reference/webhooks/card-operation-event) |
| 6 | 查询卡交易记录，并接收交易事件通知。 | [查询交易记录](/zh/issuing/api-reference/endpoints/query-transaction-records) |

## 下一步

- [接口说明](/zh/issuing/api-reference) — 查看发卡 API 公共规则
- [创建持卡人](/zh/issuing/api-reference/endpoints/create-cardholder) — 开卡前创建持卡人
- [创建卡片](/zh/issuing/api-reference/endpoints/create-card) — 创建第一张虚拟卡
- [事件推送](/zh/issuing/api-reference/webhooks/card-operation-event) — 配置卡操作和卡交易事件处理