# 1. 收银台功能介绍

Gate Pay提供的动态托管收银台页面服务。用户在app内确认订单后，可跳转到内嵌的Gate Pay收银台H5页面完成支付：

支持用户通过Gate App扫码完成付款；也可以通过其他三方钱包，向地址转账完成付款。后续我们会在页面中增加调起支付等其他支付方式，供用户选择。

# 2.收银台核心流程

# 2.1 收银台流程图

# 2.2 调用流程

1-6步骤：用户选择商品，在商户App里创建订单请求，商户App调用收银台预付单创建接口(/v1/pay/checkout/order), 在

预付单创建成功后，Gate Pay返回订单信息给商户。

7-11步骤：商户成功创建收银台订单后，根据响应localtion地址(该地址为创建预付单返回信息localtion字段)跳转到收银台，GatePay验证跳转订单合法性，如果验证成功返回订单详细信息，并拉起收银台组件。

12-14步骤：在收银台用户可以选择扫码支付或地址支付等付款方式，GatePay在确认用户订单付款完成后，会异步通知订单状态给商户后端。

# 3.商户接入收银台步骤

# 3.1 Gate Pay接入准备

请参考Gate Pay接入准备文档

# 3.2 获取地址支付链信息

商户在调用收银台下单接口(/v1/pay/checkout/order)时，需要传入链和链网络信息,改信息获取接口步骤如下。

使用接口(/v1/pay/address/currencies)查询支持的地址支付币种列表。
在获取到支持币种列表后，在使用接口(/v1/pay/address/chains)获取币种链网络信息。

# 3.3 商户调起Gate Pay收银台

商户后端服务在使用收银台下单接口(/v1/pay/checkout/order)下单成功后，根据下单接口返回localtion字段跳转到收银台。

收银台跳转地址格式如下:

https://www.gate.com/cashier?prepayid=65466648727916544

# 3.4 商户后端获取订单信息

用户在支付成功后，Gate Pay会异步通知订单状态。支付订单异步通知详细信息可以参考Gate Pay接入准备文档支付回调和查单实现指引章节

# 3.5 收银台相关API列表

# 3.5.1 收银台下单

数据类型：JSON （content-type： application/json）
请求方式：POST
Path: /v1/pay/checkout/order
验证方式：签名验证
请求体内容:

字段名	类型	是否必须	说明
`merchantTradeNo`	`string`	是	商户订单号
`currency`	`string`	是	订单币种，大写形式，如USDT、BTC等
`orderAmount`	`string`	是	订单金额，最小值0.000001，最高精度为6位
`payCurrency`	`string`	否	地址支付的付款币种，不传payCurrency就和currency相同
`env`	`Env type`	是	交易来源
`goods`	`goods type`	是	商品说明
`orderExpireTime`	`int64`	否	订单过期绝对时间单位毫秒。不设置时默认为1小时，最大过期时间为1小时
`returnUrl`	`string`	否	订单支付成功后返回跳转地址，最长256字符
`cancelUrl`	`string`	否	订单支付失败后返回跳转地址，最长256字符
`merchantUserId`	`int64`	是	支付者在商户平台注册时的唯一ID
`chain`	`string`	是	所选链名字,商户侧可调用/v1/pay/address/chains接口获取，接口请参考地址支付文档
`fullCurrType`	`string`	是	包含链名字的币种字段，对应到具体链的具体币种
`channelId`	`string`	否	客户名称

Env type

字段名	类型	是否必须	说明
`terminalType`	`string`	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS

Goods type

字段名	类型	是否必须	商品名称，最长160字符
`goodsName`	`string`	是	商品名称，最长160字符
`goodsDetail`	`string`	否	商品描述，最长256字符
`goodsType`	`string`	否	商品分类

请求示例:

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/order' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantTradeNo": "163",
    "env": {
        "terminalType": "APP"
    },
    "currency": "USDT",
    "orderAmount": "118.75",
    "merchantUserId": 123,
    "goods": {
        "goodsType": "02",
        "goodsName": "Sipariş Ödemesi - 177",
        "goodsDetail": "Sipariş No : 160"
    },
    "returnUrl": "https://lotkeys.com/tr/gate-payment-response",
    "cancelUrl": "https://lotkeys.com/tr/gate-payment-response",
    "chain": "MATIC",
    "fullCurrType": "USDT_MATIC",
    "channelId": "123456"
}'

响应：

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "65466648727916544",
        "terminalType": "APP",
        "expireTime": 1677573665219,
        "qrContent": "http://openplatform.gate.io/qr/GA0cskPehKxQpshvm3Goeve8dHpwCl6yCHLSWUYrLqo=",
        "location": "https://www.gate.com/cashier?prepayid=65466648727916544",
        "payCurrency": "USDT",
        "payAmount": "1",
        "chain": {
            "chain_type": "BSC",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "fullCurrType": "USDT_EOS"
        }
    }
}

响应字段：

字段名	类型	是否必须	说明
`status`	`string`	是	SUCCESS 或者 FAIL
`code`	`string`	是	出错代码
`data`	`data type`	否	退款单信息
`errorMessage`	`string`	否	错误信息

date格式:

字段名	类型	说明
`prepayId`	`string`	创建成功的预订单id
`terminalType`	`string`	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
`expireTime`	`int64`	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
`qrContent`	`string`	订单二维码（有效时间 1 小时）以字符串的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
`location`	`string`	下单成功调起收银台跳转地址
`payCurrency`	`string`	地址支付付款币种
`payAmount`	`string`	地址支付需要支付的金额
`chain`	`chain 结构`	地址支付链信息结构

字段名	类型	说明
`chain_type`	`string`	链名称
`address`	`string`	订单绑定的链收款地址
`fullCurrType`	`string`	包含链名字的币种字段，对应到具体链的具体币种

# 3.5.2 收银台退款接口

数据类型：JSON （content-type： application/json）
请求方式：POST
Path: /v1/pay/checkout/refund
验证方式：签名验证
请求体内容:

字段名	类型	是否必须	说明
`refundRequestId`	`string`	是	商户退款ID,由商户生成唯一ID并保证小于32字节
`prepayId`	`string`	是	订单ID,订单必须是完成支付状态才能发起退款
`refundOrderCurrency`	`string`	是	退款订单币种
`refundOrderAmount`	`string`	是	退款商户已收到的用户支付的全部金额
`refundPayCurrency`	`string`	是	退款订单支付币
`refundPayAmount`	`string`	是	用户支付后，退款残留于链上的金额。商户没有收到这部分资金（闪兑场景）
`refundReason`	`string`	是	退款原因
`receiverId`	`int64`	是	地址支付退款接收人在gate系统的user_id

请求示例：

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1697517106839' \
--header 'X-GatePay-Nonce: 3867712705' \
--header 'X-GatePay-Signature: 9f0532870be67e51ccf5adb3f7ce4532d7b0ec692b53ed94654f8b5c6fb257d8c1e60d1d074ea783c7f10ea2dc479e43b4989ff8efaed22aec5c67e797424b93' \
--data '{
    "refundRequestId": "100036668891329",
    "prepayId": "93752669101887488",
    "refundOrderCurrency": "USDT",
    "refundOrderAmount": "100",
    "refundPayCurrency": "USDT",
    "refundPayAmount": "50",
    "refundReason": "test refund",
    "receiverId": 6790011
}'

响应示例：

{
    "status": "SUCCESS",
    "code": "00000",
    "errorMessage": "",
    "data": {
        "refundRequestId": "32111114322523534534",
        "prepayId": "50620368071692288",
        "orderCurrency": "BTC",
        "orderAmount": "2",
        "refundOrderAmount": "1",
        "payCurrency": "BTC",
        "payAmount": "2",
        "refundPayAmount": "0"
    }
}

响应参数:

字段名	类型	说明
`refundRequestId`	`string`	商户退款请求id
`prepayId`	`string`	拟退款的订单id
`orderCurrency`	`string`	订单币种
`orderAmount`	`string`	订单金额
`refundOrderAmount`	`string`	退款商户已收到的用户支付的全部金额
`payCurrency`	`string`	用户支付币种
`payAmount`	`string`	订单中用户应该支付的金额
`refundPayAmount`	`string`	用户支付后，退款残留于链上的金额。商户没有收到这部分资金（闪兑场景）

# 3.5.3 收银台单详情查询

由于收银台具有地址支付订单的所有特性，其订单状态比扫码支付等常规支付方式更丰富，因此详情端口参考6.5 地址支付订单详情查询

# 4. 收银台支付的消息通知说明

收银台支付中存在Gate支付和Web3支付（地址支付）

其中Gate支付的消息通知见4. 订单状态异步通知

收银台中地址支付的消息通知见4. 消息通知

# 5. 常见问题

# Q:订单有效期为多久

A: 商户可在创建预付单接口指定过期时间，最大和默认有效期都为一小时。

# Q:接口里签名如何计算

A:可参考GatePay接入准备文档里安全要求章节。

# Q:什么是地址支付延迟支付

A: 定义: 检测到链上交易记录广播的时刻在订单结束后或有效期之后的支付记录，称为延迟支付。

非闪兑延迟支付单资金：将用户支付资金充值到商户支付账户

闪兑延迟支付单资金：将用户支付资金保留在Gate，不充值到商户支付账户

# Q: 商户后端如何获取订单支付结果

A:用户在支付成功后，Gate Pay会异步通知订单状态给商户后端。支付订单异步通知详细信息可以参考Gate Pay接入准备文档支付回调和查单实现指引章节

Last Updated: 6/11/2025, 9:38:28 AM