# 接入准备

> 开通沙盒账户、获取 API 凭证并配置 IP 白名单，在正式上线前完成首笔测试交易。

接入 Onerway Payments 时，先激活沙盒账户、获取 API 凭证并配置沙盒 IP 白名单。在沙盒环境完成集成开发与测试后，再配置生产环境并上线。

## 接入步骤

<steps level="3">

### 激活沙盒账户

向 Onerway 技术支持提供**注册邮箱**（用于接收开户邮件，邮件内含商户后台登录链接、商户号及初始登录账号等信息。）和**测试域名**（用于开通测试应用。一个域名或 IP 对应一个商户站点/应用，支持泛域名（如 `*.example.com`）。），收到邮件邀请后点击链接，商户账户即在沙盒中激活。

通过 Web SDK 或 API 直连在自有页面展示 Apple Pay 按钮的商户，需为对应的测试与生产域名完成 Apple 域名验证（收银台为 Onerway 托管页面，无需此步骤），见 [Apple Pay 接入准备](/zh/payments/online-payments/payment-methods/apple-pay#%E6%8E%A5%E5%85%A5%E5%87%86%E5%A4%87)。

通过 API 直连接入 Google Pay 时，需完成[上线前网站报备](/zh/payments/online-payments/payment-methods/google-pay#%E4%B8%8A%E7%BA%BF%E5%89%8D%E7%BD%91%E7%AB%99%E6%8A%A5%E5%A4%87)；收银台和 Web SDK 无需报备。

### 获取凭证

登录商户后台，获取以下 API 凭证，供服务端调用 API 时使用。

| 凭证 | 后台路径 | 直达链接 |
| --- | --- | --- |
| `merchantNo`（Onerway 分配的商户唯一标识。） | 设置 → 用户信息 | [沙盒](https://sandbox-merchant.onerway.com/settings/user/info) · [生产](https://merchant.onerway.com/settings/user/info) |
| `appId`（标识发起支付的商户应用或店铺，不同 appId 可对应不同的支付配置。） | 设置 → 支付 → 应用列表 | [沙盒](https://sandbox-merchant.onerway.com/settings/payment/application/list) · [生产](https://merchant.onerway.com/settings/payment/application/list) |
| `secret`（用于对每笔 API 请求加签的密钥，请保存在服务端。） | 开发者 → API 凭证 | [沙盒](https://sandbox-merchant.onerway.com/develops/api-keys) · [生产](https://merchant.onerway.com/develops/api-keys) |

<warning>

请将 `secret` 保存在服务端，切勿暴露在客户端代码、移动端安装包或版本控制系统中。

</warning>

### 配置 IP 白名单

首次从服务端调用沙盒 API 前，必须将服务端使用的所有公网出口 IP 地址加入沙盒 IP 白名单。登录沙盒商户后台，在 **开发者 → IP 白名单**中添加这些地址。此处填写服务端的出口 IP，不要填写客户设备或浏览器访问网站时使用的 IP。

沙盒和生产环境的 IP 白名单需要分别配置。上线前，必须在生产商户后台添加生产服务端使用的所有公网出口 IP 地址。即使两个环境的出口 IP 相同，也需分别添加。

| 环境 | 配置时机 | 后台入口 |
| --- | --- | --- |
| 沙盒环境 | 首次从服务端调用沙盒 API 前 | [沙盒 IP 白名单](https://sandbox-merchant.onerway.com/develops/ip-allowlist) |
| 生产环境 | 首次从服务端调用生产 API 前 | [生产 IP 白名单](https://merchant.onerway.com/develops/ip-allowlist) |

启用 IP 白名单后，请求来源 IP 不在对应环境的白名单中时，请求可能被拒绝。

### 构建与测试

配置沙盒 IP 白名单后，使用沙盒凭证开发集成，验证所有支付流程、异常处理和 Webhook 回调。切换至生产环境 API 地址和凭证前，必须将生产服务端的公网出口 IP 加入生产 IP 白名单。同时完成所用支付方式的接入要求，例如 Apple Pay 域名验证或 Google Pay 网站报备。

</steps>

## 下一步

- [请求签名](/zh/payments/get-started/request-signing) — 了解 Onerway 如何通过签名鉴权，以及如何生成 `sign`
- [币种与金额校验](/zh/payments/get-started/currency-and-amount) — 在创建支付请求前校验 `orderCurrency`、`orderAmount` 和支付方式限额
- [沙盒测试](/zh/payments/get-started/testing) — 使用沙盒测试卡验证成功、失败、订阅和 token 支付场景