跳转到主要内容

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.

​
概述

GatePay OTC 在同一个业务域下提供两类结算能力：
  • On-ramp：商户使用法币买入数字货币，并将资产入账到商户账户
  • Off-ramp：商户卖出数字货币，并将法币结算到已审核银行账户
两类流程共享同一套接入基础：
  • 服务端签名调用
  • 下单前先获取报价
  • 银行账户治理
  • 通过主动查询和回调跟踪状态
从接入角度看，OTC 更接近“结算产品”，而不是普通零售收银产品。商户通常需要在服务端管理订单创建、银行账户选择、回调消费和对账流程。因此，稳定的接入不仅取决于正确调用接口，也取决于对报价时效、汇款操作、状态跟踪和回调处理的整体理解。

​
共享接入要求

开始接入 OTC 前，请先确认：
  1. 商户账户已完成所需 KYC 或合规审核。
  2. 商户后端已具备 API 凭证和签名能力。
  3. 至少已创建并审核通过一个 OTC 结算银行账户。
  4. 商户所在国家或地区支持 OTC 服务。
请参见： 除了技术接入能力，建议商户在正式接入前同步完成业务流程准备：
  • 明确银行账户开户与维护方式
  • 明确报价过期和订单重试的处理方式
  • 明确回调消息如何持久化与重放
  • 明确 OTC 结算对账方式

​
共享询价 API

OTC 入金和出金都依赖报价能力。你可以在以下页面统一理解报价的业务语义、有效期和使用方式： 通过 type 区分业务方向：
  • BUY：OTC 入金
  • SELL：OTC 出金
在实际使用中，询价接口应被视为“短时有效的定价输入”，而不是长期有效的业务承诺。更稳妥的模式通常是：
  1. 在用户或操作员准备好继续执行时再获取报价
  2. 保存 quoteToken 与有效期
  3. 在有效窗口内尽快创建订单
  4. 如果时间或金额变化，则放弃旧报价并重新获取

​
OTC / On-ramp

​
业务目标

OTC On-ramp 用于商户通过银行转账完成法币付款，并将对应数字货币入账到 GatePay 商户账户。 常见场景包括资产业务充值、机构库存买入，以及商户在后续支付或结算前先完成法币资金入场。

​
典型流程

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

​
核心接口

​
最小接入链路

对于首次接入 OTC 入金，建议先用最小链路验证报价、订单创建、付款确认和状态跟踪：
  1. 获取 BUY 报价
  2. 创建入金订单
  3. 按返回银行信息完成线下汇款
  4. 汇款完成后调用确认已付款接口
  5. 通过回调与查询跟踪最终结算结果

​
接入要点

  • 报价必须在有效期内使用。
  • 入金订单需要唯一的 clientOrderId。
  • 商户必须按返回的 Gate 收款银行信息完成汇款。
  • 汇款附言或 reference 必须原样保留。
  • 只有在实际汇款完成后才应确认已付款。
对于新接入商户，建议把“确认已付款”理解为银行侧动作完成后的确认信号，而不是单纯的前端按钮点击事件。这样更符合实际结算语义。 对于入金流程，最常见的问题通常不在 API 本身，而在于“付款指令”和“实际银行汇款”之间出现偏差。因此建议完整保留银行信息和订单上下文，便于后续核对。

​
常见回调状态

  • RECHARGE_SUCCESS
  • RECHARGE_FAIL
很多系统里，回调事件先到达，但相关记录未必会在同一时间全部更新。因此建议把以下动作分开处理：
  • 回调接收
  • 业务状态确认
  • 财务入账或台账更新

​
OTC / Off-ramp

​
业务目标

OTC Off-ramp 用于商户卖出数字货币，并把法币结算到已审核通过的银行账户。 常见场景包括资金提现、商户侧法币变现，以及将数字货币资产转换为银行渠道可用的法币余额。

​
典型流程

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

​
最小接入链路

对于首次接入 OTC 出金，建议先跑通一条 SELL 链路：
  1. 获取 SELL 报价
  2. 选择已审核通过的银行账户
  3. 创建出金订单
  4. 处理回调并轮询查询
  5. 对照银行出款结果完成内部对账

​
核心接口

​
接入要点

  • 创建出金订单前应重新获取最新报价。
  • clientOrderId 应保持全局唯一。
  • 对账时应同时关注预估法币金额和最终到账金额。
  • 建议组合使用回调和详情查询作为事实依据。
对于出金流程，建议在内部系统中显式区分“已下单”“已出款”“已最终完成”三个层次，而不要只用一个业务状态覆盖整个结算过程。 对于出金流程，状态可见性尤为重要，因为它同时跨越“数字货币卖出”和“银行侧出款”两个阶段。建议不要过早将流程视为完成，更稳妥的做法是等待最终成功状态落定，并保留完整的出款元数据。

​
常见回调状态

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

​
银行账户管理

​
操作流程

  1. 提交银行账户持有人名称、账号、银行名称、SWIFT 代码等注册所需的账户信息。
  2. 提交公司经营证书、股东证明、股权结构图等支持性材料（按实际上线场景准备所需资料）。
  3. 预留约 2 天 供人工审核；此期间请定时调用 银行账户列表 接口查询状态，认证通过后即可用于结算。
银行账户治理通常应比普通应用配置更严格，因为错误银行账户可能直接带来审核升级、结算延迟或操作风险。

​
回调与对账

OTC 接入不应只依赖单一确认方式。 建议做法：
  1. 在后端创建并持久化保存报价和订单。
  2. 保存 clientOrderId、orderId 和结算元数据。
  3. 优先处理回调通知。
  4. 使用详情查询作为兜底事实来源。
  5. 将银行结算流水与 OTC 订单结果做对账映射。
对于规模较大的接入，建议额外维护更细的业务检查点，例如：
  • 已获取报价
  • 已创建订单
  • 已收到回调
  • 已通过详情核验
  • 已完成财务对账
这样可以在不改变 API 原始订单状态语义的前提下，更清晰地理解结算进度。 请参见：

​
阅读建议

如果是第一次接入 OTC，建议按以下顺序阅读：
  1. 先阅读本 OTC 指南，理解业务模型。
  2. 再阅读 商户接入 和 认证。
  3. 阅读共享的 OTC 报价 页面。
  4. 根据实际接入方向继续阅读入金或出金的下单与查询页面。
  5. 最后阅读回调与对账相关页面。