> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OTC

> 统一说明 GatePay OTC 入金与出金的接入指南。

## 概述

GatePay OTC 在同一个业务域下提供两类结算能力：

* **On-ramp**：商户使用法币买入数字货币，并将资产入账到商户账户
* **Off-ramp**：商户卖出数字货币，并将法币结算到已审核银行账户

两类流程共享同一套接入基础：

* 服务端签名调用
* 下单前先获取报价
* 银行账户治理
* 通过主动查询和回调跟踪状态

从接入角度看，OTC 更接近“结算产品”，而不是普通零售收银产品。商户通常需要在服务端管理订单创建、银行账户选择、回调消费和对账流程。因此，稳定的接入不仅取决于正确调用接口，也取决于对报价时效、汇款操作、状态跟踪和回调处理的整体理解。

## 共享接入要求

开始接入 OTC 前，请先确认：

1. 商户账户已完成所需 KYC 或合规审核。
2. 商户后端已具备 API 凭证和签名能力。
3. 至少已创建并审核通过一个 OTC 结算银行账户。
4. 商户所在国家或地区支持 OTC 服务。

请参见：

* [认证](/essentials/version/100/cn/common/authentication)
* [商户接入](/essentials/version/100/cn/common/accessguide)

除了技术接入能力，建议商户在正式接入前同步完成业务流程准备：

* 明确银行账户开户与维护方式
* 明确报价过期和订单重试的处理方式
* 明确回调消息如何持久化与重放
* 明确 OTC 结算对账方式

## 共享询价 API

OTC 入金和出金都依赖报价能力。你可以在以下页面统一理解报价的业务语义、有效期和使用方式：

* [OTC 报价](/api-reference/version/100/cn/endpoint/otc/quote)

通过 `type` 区分业务方向：

* `BUY`：OTC 入金
* `SELL`：OTC 出金

在实际使用中，询价接口应被视为“短时有效的定价输入”，而不是长期有效的业务承诺。更稳妥的模式通常是：

1. 在用户或操作员准备好继续执行时再获取报价
2. 保存 `quoteToken` 与有效期
3. 在有效窗口内尽快创建订单
4. 如果时间或金额变化，则放弃旧报价并重新获取

## OTC / On-ramp

### 业务目标

OTC On-ramp 用于商户通过银行转账完成法币付款，并将对应数字货币入账到 GatePay 商户账户。

常见场景包括资产业务充值、机构库存买入，以及商户在后续支付或结算前先完成法币资金入场。

### 典型流程

```text theme={null}
获取报价 -> 创建入金订单 -> 获取 Gate 收款银行信息 -> 完成线下汇款 -> 确认已付款 -> 跟踪结算状态 -> 资产到账
```

### 核心接口

* [OTC 报价](/api-reference/version/100/cn/endpoint/otc/quote)
* [创建入金订单](/api-reference/version/100/cn/endpoint/otc/deposit-create)
* [确认已付款](/api-reference/version/100/cn/endpoint/otc/deposit-confirm)
* [取消入金订单](/api-reference/version/100/cn/endpoint/otc/deposit-cancel)
* [入金订单详情](/api-reference/version/100/cn/endpoint/otc/deposit-detail)
* [入金订单列表](/api-reference/version/100/cn/endpoint/otc/deposit-list)
* [OTC 回调通知](/api-reference/version/100/cn/endpoint/otc/callback)

### 最小接入链路

对于首次接入 OTC 入金，建议先用最小链路验证报价、订单创建、付款确认和状态跟踪：

1. 获取 `BUY` 报价
2. 创建入金订单
3. 按返回银行信息完成线下汇款
4. 汇款完成后调用确认已付款接口
5. 通过回调与查询跟踪最终结算结果

### 接入要点

* 报价必须在有效期内使用。
* 入金订单需要唯一的 `clientOrderId`。
* 商户必须按返回的 Gate 收款银行信息完成汇款。
* 汇款附言或 reference 必须原样保留。
* 只有在实际汇款完成后才应确认已付款。

对于新接入商户，建议把“确认已付款”理解为银行侧动作完成后的确认信号，而不是单纯的前端按钮点击事件。这样更符合实际结算语义。

对于入金流程，最常见的问题通常不在 API 本身，而在于“付款指令”和“实际银行汇款”之间出现偏差。因此建议完整保留银行信息和订单上下文，便于后续核对。

### 常见回调状态

* `RECHARGE_SUCCESS`
* `RECHARGE_FAIL`

很多系统里，回调事件先到达，但相关记录未必会在同一时间全部更新。因此建议把以下动作分开处理：

* 回调接收
* 业务状态确认
* 财务入账或台账更新

## OTC / Off-ramp

### 业务目标

OTC Off-ramp 用于商户卖出数字货币，并把法币结算到已审核通过的银行账户。

常见场景包括资金提现、商户侧法币变现，以及将数字货币资产转换为银行渠道可用的法币余额。

### 典型流程

```text theme={null}
获取报价 -> 创建出金订单 -> 等待处理 -> 银行出款 -> 跟踪结果 -> 确认最终结算
```

### 最小接入链路

对于首次接入 OTC 出金，建议先跑通一条 `SELL` 链路：

1. 获取 `SELL` 报价
2. 选择已审核通过的银行账户
3. 创建出金订单
4. 处理回调并轮询查询
5. 对照银行出款结果完成内部对账

### 核心接口

* [OTC 报价](/api-reference/version/100/cn/endpoint/otc/quote)
* [创建出金订单](/api-reference/version/100/cn/endpoint/otc/withdraw-create)
* [出金订单详情](/api-reference/version/100/cn/endpoint/otc/withdraw-detail)
* [出金订单列表](/api-reference/version/100/cn/endpoint/otc/withdraw-list)
* [OTC 回调通知](/api-reference/version/100/cn/endpoint/otc/callback)

### 接入要点

* 创建出金订单前应重新获取最新报价。
* `clientOrderId` 应保持全局唯一。
* 对账时应同时关注预估法币金额和最终到账金额。
* 建议组合使用回调和详情查询作为事实依据。

对于出金流程，建议在内部系统中显式区分“已下单”“已出款”“已最终完成”三个层次，而不要只用一个业务状态覆盖整个结算过程。

对于出金流程，状态可见性尤为重要，因为它同时跨越“数字货币卖出”和“银行侧出款”两个阶段。建议不要过早将流程视为完成，更稳妥的做法是等待最终成功状态落定，并保留完整的出款元数据。

### 常见回调状态

* `WITHDRAW_DISPATCHED`
* `WITHDRAW_SUCCESS`
* `WITHDRAW_FAIL`

在很多场景中，`WITHDRAW_DISPATCHED` 更适合作为“出款已发起”的阶段性状态，而不是最终结算完成标志。这样更利于区分“银行已出款”和“业务已完全闭环”。

## 银行账户管理

### 操作流程

1. 提交银行账户持有人名称、账号、银行名称、SWIFT 代码等注册所需的账户信息。
2. 提交公司经营证书、股东证明、股权结构图等支持性材料（按实际上线场景准备所需资料）。
3. 预留约 **2 天** 供人工审核；此期间请定时调用 [银行账户列表](/api-reference/version/100/cn/endpoint/otc/bank-list) 接口查询状态，认证通过后即可用于结算。

* [银行可用国家](/api-reference/version/100/cn/endpoint/otc/bank-countries)
* [创建银行账户](/api-reference/version/100/cn/endpoint/otc/bank-create)
* [提交银行账户补充材料](/api-reference/version/100/cn/endpoint/otc/bank-material-supplement)
* [银行账户列表](/api-reference/version/100/cn/endpoint/otc/bank-list)
* [删除银行账户](/api-reference/version/100/cn/endpoint/otc/bank-delete)

银行账户治理通常应比普通应用配置更严格，因为错误银行账户可能直接带来审核升级、结算延迟或操作风险。

## 回调与对账

OTC 接入不应只依赖单一确认方式。

建议做法：

1. 在后端创建并持久化保存报价和订单。
2. 保存 `clientOrderId`、`orderId` 和结算元数据。
3. 优先处理回调通知。
4. 使用详情查询作为兜底事实来源。
5. 将银行结算流水与 OTC 订单结果做对账映射。

对于规模较大的接入，建议额外维护更细的业务检查点，例如：

* 已获取报价
* 已创建订单
* 已收到回调
* 已通过详情核验
* 已完成财务对账

这样可以在不改变 API 原始订单状态语义的前提下，更清晰地理解结算进度。

请参见：

* [通知](/essentials/version/100/cn/common/notification)
* [OTC 回调通知](/api-reference/version/100/cn/endpoint/otc/callback)

## 阅读建议

如果是第一次接入 OTC，建议按以下顺序阅读：

1. 先阅读本 OTC 指南，理解业务模型。
2. 再阅读 [商户接入](/essentials/version/100/cn/common/accessguide) 和 [认证](/essentials/version/100/cn/common/authentication)。
3. 阅读共享的 [OTC 报价](/api-reference/version/100/cn/endpoint/otc/quote) 页面。
4. 根据实际接入方向继续阅读入金或出金的下单与查询页面。
5. 最后阅读回调与对账相关页面。