# 概览

> 跨境资金划转与打款服务。

在调用 Transfer API 之前，请先完成沙盒开户、白名单配置和商户凭证准备。建议先把环境和商户信息准备好，再进入签名和集成流程。

## 概述

<tip>

沙盒环境和生产环境的差异主要在请求域名。建议先在沙盒环境完成联调，再切换到生产环境。

</tip>

环境准备主要包括以下事项：

- 提供开户邮箱
- 提供测试对接域名
- 等待开通邮件
- 登录商户后台获取商户凭证
- 完成白名单和后续配置

## 环境说明

生产环境和沙盒环境的请求地址仅域名不同。也就是说，接入流程通常是：

1. 先在沙盒环境完成联调
2. 验证签名和打款流程
3. 再切换生产域名和生产配置

这样可以先在测试环境暴露问题，避免把环境和业务问题叠加到生产切换阶段。

## 环境域名

| 环境 | 域名 |
| --- | --- |
| 沙盒环境 | `https://sandbox-api.onerway.com/payout` |
| 生产环境 | `https://api.onerway.com/payout` |

## 商户开通与白名单

创建沙盒测试商户前，请先准备：

- 开户邮箱
- 对接测试使用的域名

开户邮箱会用于创建沙盒账户。提交的域名会被加入白名单，只有白名单中的域名才能调用 Onerway API。

这意味着在环境准备阶段，除了“有没有账号”，还要确认：

- 域名是否已经提交
- 域名是否已经加入白名单
- 当前实际发起请求的来源是否与白名单配置一致

如果域名未完成白名单配置，即使请求报文本身正确，也可能无法正常调用接口。

## 商户凭证

收到开通邮件后，请通过邮件中的商户后台链接登录。首次登录需要先重置密码，随后获取商户凭证。

在 Transfer 中，请使用实际请求字段名 `merchantNo`。

您通常需要准备：

- `merchantNo`
- 与签名方式对应的密钥或私钥

<warning>

Transfer 文档统一使用 `merchantNo`，不要替换成 `merchantId`。

</warning>

## 字段必填标识

字段表使用以下标识：

| 标识 | 含义 |
| --- | --- |
| `M` | 必填 |
| `C` | 条件必填 |
| `N` | 选填 |

## 接入前准备清单

在开始构造请求报文、创建收款方或发起打款前，请确认：

1. 沙盒账户已开通
2. 对接域名已加入白名单
3. 已从商户后台获取商户凭证
4. 已确认签名方式
5. 已确认目标国家、币种、打款方式和主体类型下的必填字段

完成这里的准备后，后续通常继续进入：

- 请求签名准备
- 集成流程确认
- Sandbox 测试与上线准备

## 继续阅读

- [请求签名](/zh/transfer/get-started/request-signing)
- [集成流程](/zh/transfer/get-started/integration-flow)
- [测试与上线](/zh/transfer/get-started/testing-and-go-live)