支付 - Gate Pay DOCS

概述

GatePay 提供多种收款方式，以适配不同的商户和用户场景：

托管收银台支付：由 GatePay 托管支付界面，支持二维码支付和链上动态地址支付
地址支付：直接向动态生成或静态收款地址发起付款
支付拉起：适用于移动端和客户端的应用内支付拉起场景

托管收银台支付

产品概述

托管收银台支付是由 GatePay 提供的完整收款能力。商户无需自行建设支付页面，GatePay 会统一处理以下方式：

二维码支付
链上动态地址支付（Web3）

支付流程

托管收银台支付流程主要包含三个步骤:

创建预订单: 商户创建预订单，并从 API 获取重定向信息。
用户重定向: 商户使用返回的 location URL 将用户重定向到 GatePay 托管收银台页面。
异步通知: 用户完成支付后，GatePay 会通过回调异步通知商户后端订单状态。

重要: 商户不得手动拼接收银台 URL。请始终使用 API 返回的 location 值.

查询支持的链

请求:

GET /v1/pay/address/chains

查询 Web3 地址支付支持的区块链网络列表。该接口可帮助你确认支付币种可使用哪些链.

创建托管收银台订单

请求:

POST /v1/pay/checkout/order

创建新的托管收银台订单。成功后，API 会返回 location 字段，你必须使用该字段将用户重定向到支付页面。该 URL 是进入 GatePay 托管收银台的唯一有效入口.

参数说明

托管收银台订单的完整字段以 API Reference 和 OpenAPI 定义为准。不同收款模式下，请求体中可能会组合出现订单信息、用户信息、环境信息、商品信息以及链路相关字段。接入时建议重点关注以下几类信息：

订单唯一标识，例如 merchantTradeNo
金额与币种信息
用户或终端上下文信息
商品与展示信息
回调与跳转地址
链路相关字段，例如链和币种组合

如果你是第一次接入，不建议只凭本页文字手写请求体；更稳妥的方式是直接对照对应的 API Reference 页面和 OpenAPI schema 实现。

响应字段

字段	类型	说明
`prepayId`	字符串	用于跟踪和查询的 GatePay 预订单 ID
`location`	字符串	托管收银台重定向 URL。请将用户重定向到该 URL。
`qrContent`	字符串	二维码支付使用的二维码内容 (如适用)

最小可运行示例

如果你想先跑通第一条支付链路，下面这组最小示例比字段总表更适合直接落地。 创建订单

curl -X POST "https://openplatform.gateapi.io/v1/pay/checkout/order" \
  -H "Content-Type: application/json" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1710000000000" \
  -H "X-GatePay-Nonce: checkout001" \
  -H "X-GatePay-Signature: generated_signature" \
  -d '{
    "merchantTradeNo": "M202604150001",
    "currency": "USDT",
    "orderAmount": "10.00",
    "goods": {
      "goodsName": "Demo Order",
      "goodsDetail": "Checkout quickstart"
    },
    "callbackUrl": "https://merchant.example.com/webhook/gatepay",
    "returnUrl": "https://merchant.example.com/result"
  }'

典型成功响应重点

取得 prepayId
取得 location
前端使用 location 跳转

后续链路

等待 PAY 回调
再调用 GET /v2/pay/order/query 做最终确认
关键订单建议同时保存 merchantTradeNo 与 prepayId

查询订单结果

请求:

GET /v2/pay/order/query

查询订单当前状态和详情。该接口是支付确认和对账的关键接口. 建议把该接口视为“支付结果最终确认接口”，而不是仅用于异常时排查。即使已经接收到成功回调，商户在关键流程中仍可按需结合本接口进行二次确认。

不同支付方式的查询入口

托管收银台支付：GET /v2/pay/order/query
地址支付：GET /v1/pay/address/query
扫码 / Web 拉起支付：请按对应 API Reference 页面使用该产品实际暴露的查询接口

不要把不同产品线的查单接口混用。即使字段名称相近，不同产品的状态语义、金额字段和补充信息也可能不同。

支付金额处理方式

支付金额的解释方式会根据订单类型而不同:

Gate 支付（非地址）: 最终实付金额由以下字段表示 orderAmount.
地址支付: 需要同时考虑 waitAmountOnChain 和 doneAmountOnChain:
- waitAmountOnChain: 已检测到但尚未最终确认的链上金额
- doneAmountOnChain: 已确认并入账到商户账户的链上金额

签名请求与回调

有关请求签名和回调验签的安全详情，请参见认证与安全。

地址支付

地址支付支持直接向区块链地址收款。系统会根据订单参数动态生成支付地址，或使用预先配置的静态地址。

典型接入流程

查询链: 查询订单币种支持的链。
创建订单: 系统会生成并返回唯一收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）
用户支付: 用户向收款地址转账。
支付检测: GatePay 检测链上交易，并通过回调通知你的后端。
结果确认: 通过回调确认支付，或使用查询 API 作为兜底。

订单状态

常见 PAY_ADDRESS 订单状态：

状态	说明
`PAY_SUCCESS`	支付成功且资金已入账
`PAY_ERROR`	支付失败；资金未入账
`PAY_CLOSE`	订单被商户或系统关闭
`PAY_EXPIRED_IN_PROCESS`	订单有效期已过，但仍有部分链上交易未确认。确认后资金仍可能入账。

支付模式选择: 非兑换 vs. 兑换

非兑换模式: 资金按原支付币种入账。 兑换模式: 资金会在入账前兑换为其他币种。对于兑换模式订单，你可能需要查询支持的兑换币种。

查询支持的兑换币种 (仅兑换模式)

请求:

GET /v1/pay/address/supportedconvertcurrencies

列出地址支付支持自动兑换的币种。

创建地址支付订单

请求:

POST /v1/pay/address/create

系统会生成并返回唯一收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）当你在“非兑换”和“兑换”模式之间切换时，建议同时检查订单币种、支付币种和后续回调字段的解释方式，避免把不同模式下的字段含义混为一谈。

查询地址支付订单

请求:

GET /v1/pay/address/query

查询地址支付订单当前状态，包括链上检测结果和确认状态。

静态地址支付

静态地址支付支持商户为长期或周期性收款场景配置固定收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写），适用于:

订阅或周期性账单
打赏或募资页面
商户结算账户
佣金分发

工作方式

配置静态地址: 使用保存接口为指定渠道和区块链配置固定收款地址。若使用 Ton 链，还会返回 Memo 字段（为防止造成资产丢失，用户付款时必须填写）
复用地址: 在多笔订单中复用同一地址和 Memo（如有），无需每次创建新地址
自动检测: GatePay 检测到静态地址收款后会发送通知。

如果同一 channelId 和 chain 已存在配置，API 会更新该配置.

保存或更新静态地址配置

请求:

POST /v1/pay/fixedaddress/save

为指定的 channelId 和区块链网络（chain）保存或更新静态地址配置.

支付拉起

支付拉起支持移动应用或客户端 Web 应用中的应用内支付体验。该流程允许用户无需离开应用即可直接发起支付.

接入步骤

服务端预订单: 在后端使用收银台订单接口创建预订单。
客户端拉起: 将 prepayId 传给客户端应用。
客户端查询: 客户端可按需查询订单状态以更新界面。
参数校验: 拉起支付流程前校验支付参数。
最终确认: 用户返回后，通过服务端查询确认支付状态。

客户端 SDK 参数校验

请求:

POST /v1/pay/open/sdk

校验支付参数并为支付拉起准备 SDK。发起客户端支付流程前，请使用该接口校验 prepayId 和其他参数.

服务端预订单响应字段

创建用于支付拉起的预订单后，响应会包含:

字段	类型	说明
`prepayId`	字符串	需要传给客户端 SDK 的预订单 ID
`location`	字符串	重定向 URL（用于基于 Web 的支付拉起）
`qrContent`	字符串	二维码内容（可选，用于二维码流程）

客户端返回与支付确认

关键提示: 客户端应用返回商户页面后，重定向结果或客户端状态绝不能作为最终支付结果. 请始终通过服务端查询 GET /v2/pay/order/query 来确认支付状态。这可以确保:

系统中的支付状态准确
正确处理待确认或延迟支付
欺诈检测和对账

支付有效期与过期

默认有效期

默认情况下，订单自创建起 1 小时 内有效。可通过 orderExpireTime 参数配置有效期.

延迟支付处理

如果区块链交易在订单过期后提交，该支付会被归类为延迟支付。GatePay 支持两种处理模式:

非兑换延迟支付: 即使订单已过期，资金在链上确认后仍会入账到商户账户.
兑换延迟支付: 用户资金不会进入商户支付账户，该订单按失败处理.

退款

为保持向后兼容，GatePay 提供两个退款 API:

标准退款（推荐）

请求:

POST /v2/pay/order/refund

面向新接入的标准退款接口。所有新实现都应使用该接口.

兼容退款（旧版）

请求:

POST /v1/pay/order/refund

旧版退款接口。仅为已有接入保留，新接入必须使用 v2 接口. 需要特别区分：

API 发起的退款：按本文档中的接口与回调模型接入
商户后台手工退款：处理进度以后台展示为准，不应假设一定沿用同样的 API 回调节奏

回调与异步通知

所有支付方式都支持异步回调，用于通知你的后端订单状态变化。有关完整的回调详情、载荷结构、签名与验签，请参见通知与回调。 GatePay 保证:

回调会按照具体订单流程中的回调配置或回调参数进行投递
回调包含已签名载荷以便安全验证
如果首次投递失败，会进行多次回调重试

对于支付链路，建议始终把“回调通知”和“订单查询”组合使用：

回调用于及时推进业务流程
查询用于最终确认和兜底核验

如果你更希望先从完整链路开始接入，而不是按章节阅读，请先参见快速开始。

最佳实践

始终验证回调: 使用每次回调携带的签名进行验证。见认证与安全.
使用查询作为兜底: 如果回调投递延迟或遗漏，请使用查询接口进行对账。
处理延迟支付: 实现逻辑以处理订单过期后到账的支付。
监控金额字段: 对于地址支付，请始终同时检查 waitAmountOnChain 和 doneAmountOnChain，以获得完整支付情况。
保存 prepayId: 保存订单创建时返回的 prepayId，用于跟踪和支持。
实现幂等性: 使用唯一的 merchantTradeNo 防止重复订单。

​概述

​托管收银台支付

​产品概述

​支付流程

​查询支持的链

​创建托管收银台订单

​参数说明

​响应字段

​最小可运行示例

​查询订单结果

​不同支付方式的查询入口

​支付金额处理方式

​签名请求与回调

​地址支付

​典型接入流程

​订单状态

​支付模式选择: 非兑换 vs. 兑换

​查询支持的兑换币种 (仅兑换模式)

​创建地址支付订单

​查询地址支付订单

​静态地址支付

​工作方式

​保存或更新静态地址配置

​支付拉起

​接入步骤

​客户端 SDK 参数校验

​服务端预订单响应字段

​客户端返回与支付确认

​支付有效期与过期

​默认有效期

​延迟支付处理

​退款

​标准退款（推荐）

​兼容退款（旧版）

​回调与异步通知

​最佳实践

​相关文档

概述