# 1. 收银台功能介绍

GatePay 为商户提供专属的收银台结账页面，商户无需自行开发前端支付 UI，并同时支持扫码支付与链上动态地址支付。

# 2.收银台核心流程

# 2.1 收银台流程图

# 2.2 调用流程

1–6步骤：用户选择商品后，商户在商户端创建订单请求，并调用收银台预付单创建接口 (/v1/pay/checkout/order)。预付单创建成功后，GatePay 将订单信息返回给商户。

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位
`surchargeAmount`	`string`	否	附加费，指由消费者承担的费用
`toleranceAmount`	`string`	否	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
`fiatCurrency`	`string`	否	法币币种，大写形式，如EUR、GBP、USD、CNY、JPY、AUD、CAD、CHF
`fiatAmount`	`string`	否	法币订单金额，最小值0.01，最高精度为2位
`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

字段名	类型	是否必须	说明
`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",
        "orderAmount": "1",
        "surchargeAmount": "0",
        "currency": "USDT",
        "fiatCurrency": "",
        "fiatAmount": "",
        "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"
        },
        "channelId": "123456",
        "goodsName": "charge",
        "inUsdt": "93.99"
    }
}

响应字段：

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

data格式:

字段名	类型	说明
`prepayId`	`string`	创建成功的预订单id
`orderAmount`	`string`	订单金额
`currency`	`string`	订单加密货币币种
`surchargeAmount`	`string`	附加费，指由消费者承担的费用
`toleranceAmount`	`string`	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
`fiatCurrency`	`string`	法币币种
`fiatAmount`	`string`	法币订单金额
`terminalType`	`string`	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
`expireTime`	`int64`	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
`qrContent`	`string`	订单二维码以链接的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
`location`	`string`	下单成功调起收银台跳转地址
`payCurrency`	`string`	地址支付付款币种
`payAmount`	`string`	地址支付需要支付的金额
`chain`	`chain 结构`	地址支付链信息结构
`goodsName`	`string`	商品名称
`inUsdt`	`string`	对应的USDT的金额

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

# 3.5.2 收银台退款接口

此为旧版退款接口，推荐使用新版退款接口 3.5.3 /v2/standard/order/refund

数据类型：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 收银台退款接口 V2

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

字段名	类型	是否必须	说明
`refundRequestId`	`string`	是	商户退款ID,由商户生成唯一ID并保证小于32字节
`prepayId`	`string`	是	订单ID,订单必须是完成支付状态才能发起退款
`refundAmount`	`string`	是	退款金额
`refundReason`	`string`	是	退款原因
`refundStyle`	`int64`	否	退款方式 1:原路退 2:指定退
`refundPayChannel`	`int64`	否	退款支付方式 1:Gate 2:Web3
`refundToGateUid`	`string`	否	退款至用户id,如果是Gate则必填
`refundChain`	`string`	否	退款网络 ,如果是Web3则必填
`refundBearType`	`string`	否	退款承担类型 1:需商家承担，2:需用户承担
`memo`	`string`	否	退款备注
`refundAmountTypeFull`	`string`	否	退款金额类型 1:全部退 2:部分退
`needNotify`	`boolean`	否	是否需要通知
`refundLimit`	`boolean`	否	退款是否限制次数
`refundCurrency`	`string`	否	退款币种
`refundFundStatementId`	`int64`	否	发起退款的流水id
`refundSource`	`int64`	否	退款发起的源头，0：订单 1：流水

响应参数:

字段名	类型	说明
`refundRequestId`	`string`	商户退款请求Id
`prepayId`	`string`	订单Id
`refundGateId`	`string`	Gatepay退款单Id
`orderAmount`	`string`	订单金额
`refundAmount`	`string`	退款金额
`errMsg`	`string`	错误信息
`orderCurrency`	`订单币种`	订单币种
`payCurrency`	`订单币种`	退款币种
`payAmount`	`订单币种`	商家支付金额

请求示例：

curl --location 'https://openplatform.gateapi.io//v2/standard/order/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 '{
    "prepayId": "35214673103159414",
    "refundRequestId": "202508271923022",
    "refundStyle": 2,
    "refundToGateUid":10002,
    "refundAmount": "0.018",
    "currency": "USDT",
    "refundPayChannel": 1,
    "refundReason":"bourne-test",
    "refundBearType":1
}'

响应示例：

{
    "code": "000000",
    "data": {
        "refundRequestId": "202508271923022",
        "refundGateId": "1991045981847818240",
        "prepayId": "35214673103159414",
        "orderAmount": "10",
        "refundAmount": "0.018",
        "errMsg": "",
        "orderCurrency": "USDT",
        "payCurrency": "USDT",
        "payAmount": "0.018"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

# 3.5.4 收银台单详情查询

数据类型：JSON （content-type：application/json）
请求⽅式：GET
路径Path: /v2/pay/order/query
验证⽅式：商户签名验证

接口定义:

属性名	类型	是否必须	说明
`prepayId`	`string`	否	预付单Id
`merchantTradeNo`	`string`	否	商户订单id。预付单id与此id提供一个即可

响应参数:

属性名	类型	说明
`prepayId`	`string`	预付单id
`merchantId`	`int64`	用于申请商户账号的Gate UID
`merchantTradeNo`	`string`	商户订单
`transactionId`	`string`	交易id
`goodsName`	`string`	商品名称
`currency`	`string`	订单币种
`orderAmount`	`string`	订单金额
`surchargeAmount`	`string`	附加费，指由消费者承担的费用
`toleranceAmount`	`string`	容差金额：当订单剩余未付金额 ≤ 设置的容差金额时，系统将自动视为支付成功，无需用户额外补款。
`underpaidAmount`	`string`	支付完成后，剩余支付金额
`fiatCurrency`	`string`	订单法币币种
`fiatAmount`	`string`	法币订单金额
`fiatRate`	`string`	加密货币、法币汇率
`status`	`string`	订单状态
`createTime`	`int64`	预付单创建时间，单位毫秒
`expireTime`	`int64`	预付单过期时间，单位毫秒
`transactTime`	`int64`	支付完成时间，单位毫秒
`order_name`	`string`	订单名称
`pay_currency`	`string`	用户实际支付币种
`pay_amount`	`string`	用户实际支付金额
`expectCurrency`	`string`	商家创建订单时，指定营收币种，注：仅在商户指定结算币种的订单详情中返回
`actualCurrency`	`string`	订单支付完成后，Gate 后台实际结算到商户账户的币种
`actualAmount`	`string`	订单支付完成后，对应 Gate 后台实际结算到商户账户的币种金额
`rate`	`string`	闪兑支付时的汇率
`channelId`	`string`	客户名称
`address`	`string`	收款地址
`appLogo`	`string`	应用Logo
`appName`	`string`	应用名称
`chain`	`string`	链网络
`channel_type`	`string`	渠道类型
`fromAddress`	`string`	付款方地址
`fullCurrType`	`string`	包含链名字的币种字段
`inUsdt`	`string`	对应的USDT的金额
`location`	`string`	创建订单后，Web支付组件跳转地址
`merchantName`	`string`	供货商名称
`pay_account`	`string`	支付账户
`qrcode`	`string`	订单二维码以链接的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
`returnUrl`	`string`	订单支付成功后返回跳转地址，最长256字符
`scheme`	`string`	加密后的交易Hash
`showChainNameEn`	`string`	链的英文展示
`totalFee`	`string`	订单金额
`txHash`	`string`	交易Hash
`transaction_info`	`ChainTransactionInfo`	交易信息
`whiteBrandInfo`	`WhiteBrandInfo`	品牌信息

ChainTransactionInfo:

字段名	类型	说明
`done_amount`	`string`	完成金额
`confirming_list`	`ConfirmItem`	订单有效期内的支付记录在链上确认中的支付列表

ConfirmItem:

字段名	类型	说明
`amount`	`string`	支付记录金额
`confirm`	`int`	确认数

WhiteBrandInfo:

字段名	类型	说明
`logoUrl`	`string`	品牌Logo
`brand`	`string`	品牌
`payWays`	`array`	支付方式列表

订单Status枚举值：

值	解释
`PENDING`	订单待支付
`PROCESS`	订单处理中
`PAID`	支付成功
`EXPIRED`	订单超时
`CANCELLED`	订单被商户主动取消
`ERROR`	订单支付失败错误
`BLOCK`	静态地址收款BLOCK
`AUDITING`	订单审核中
`REJECTED`	订单审核拒绝
`AUDIT_ERROR`	审核通过支付错误

请求示例

curl --location --request GET 'https://openplatform.gateapi.io/v2/refund/support/chains?prepayId=55607130580844563' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

请求响应

{
  "code": "000000",
  "data": {
    "bizCode": "0",
    "bizData": {
      "prepayId": "55607130580844563",
      "merchantId": 1627288,
      "merchantTradeNo": "Gate-Pre-1763519042444",
      "transactionId": "",
      "goodsName": "Gate-Pre-Good-Name",
      "currency": "USDT",
      "orderAmount": "1",
      "status": "PENDING",
      "createTime": 1763519042794,
      "expireTime": 1763522642750,
      "transactTime": 0,
      "order_name": "Gate-Pre-176351904244411",
      "pay_currency": "USDT",
      "pay_amount": "1",
      "expectCurrency": "USDT",
      "actualCurrency": "",
      "actualAmount": "",
      "rate": "1",
      "channelId": "",
      "address": "0x7aD5b3E4695a85f0248d675861b44Bd968Ed22e5",
      "appLogo": "https://gimg2.staticimgs.com/image/7f4993b72edab240c4aa0be9ee5bb7f91d7b5215.png",
      "appName": "TestApp",
      "chain": "ETH",
      "channel_type": "",
      "fromAddress": "",
      "fullCurrType": "USDT_ETH",
      "inUsdt": "1",
      "location": "https://www.gate.com",
      "merchantName": "TestMerchant",
      "pay_account": "",
      "qrcode": "http://openplatform.gate.io/qr/X9HvcRyUVtqqRsizJBGHpMQ5r3IiT7OsD2dgS9cB-w8",
      "returnUrl": "https://www.gate.com",
      "scheme": "gatepay056e08b4e2e44bfe",
      "showChainNameEn": "USDT_ETH",
      "totalFee": "1",
      "transaction_info": {
        "confirming_list": [],
        "done_amount": "0"
      },
      "txHash": "",
      "whiteBrandInfo": {
        "brand": "anlitesttr",
        "logoUrl": "https://gimg2.staticimgs.com/image/1627288/edecb5338bd4b6aca36d9dcbb5d17907c5226e66911b88f6c0e232e948516880.png",
        "payWays": [
          "web3",
          "gate"
        ]
      }
    },
    "bizMessage": ""
  }, 
  "status": "SUCCESS",
  "errorMessage": ""
}

# 3.5.5 查询退款币种支持的网络

数据类型：JSON （content-type：application/json）
请求⽅式：GET
路径Path: /v2/refund/support/chains
验证⽅式：商户签名验证

接口定义:

字段名	类型	是否必须	说明
`currency`	`string`	是	拟下单的币种

响应参数:

字段名	类型	说明
`currency`	`string`	拟支付的币种
`chains`	`[] ChainItem`	拟支付币种可选Gate链列表

ChainItem结构:

字段名	类型	说明
`chain`	`string`	网络信息
`currency`	`ChainItem`	币种
`full_curr_type`	`string`	含网络信息的币种符号
`symbol`	`string`	链上交易符号
`explorer_url`	`string`	浏览地址
`show_chain_name_en`	`string`	币种英文名称
`hasWithdrawMemo`	`int`	是否有提现备注,0:无，1:有
`withdrawPercent`	`string`	提现费率百分比
`withdrawFix`	`string`	提现固定费率

查询支持链列表，请求示例

curl --location --request GET 'https://openplatform.gateapi.io/v2/refund/support/chains?currency=USDT' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

查询退款币种支持的网络，请求响应

{
  "code": "000000",
  "data": {
    "currency": "USDT",
    "chains": [
      {
        "chain": "MATIC",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "1",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "MATIC"
      },
      {
        "chain": "SOL",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "0.1",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "SOL"
      },
      {
        "chain": "ETH",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "7.4",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "ETH"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

# 3.5.6 收银台退款详情查询接口

请求类型: JSON (content-type: application/json)
请求方式：GET
PATH: /v2/pay/refund/details
验证⽅式：商户签名验证
请求参数：

属性名	类型	是否必须	说明
`refundRequestId`	`string`	是	商户生成的退款单id。退款单id必须唯一，不大于32字符

响应参数:

属性名	类型	说明
`refundRequestId`	`string`	商户退款订单号
`gateRefundId`	`string`	退款单id，GatePay生成
`refundId`	`string`	商家退款订单号
`orderId`	`string`	GatePay支付订单号
`merchantTradeNo`	`string`	商户订单号
`createTime`	`int64`	退款单创建时间
`transactTime`	`int64`	支付时间
`transactionId`	`string`	支付流水订单号
`txHash`	`string`	交易Hash,Web3退款才有
`orderAmount`	`string`	订单金额
`orderCurrency`	`string`	订单币种
`requestAmount`	`string`	申请退款金额
`requestCurrency`	`string`	申请退款币种
`amount`	`string`	退款金额
`currency`	`string`	退款币种
`status`	`string`	退款状态
`remark`	`string`	退款订单备注
`refund_style`	`string`	退款方式 1:原路退 2:指定退
`refund_pay_channel`	`string`	退款支付方式 1:gate 2:web3
`refund_address`	`string`	退款地址
`refund_chain`	`string`	退款网络
`refund_bear_type`	`string`	退款承担类型 1:需商家承担，2:需用户承担
`refund_amount_type`	`string`	退款金额类型 1:全部退 2:部分退
`refund_account_type`	`string`	退款扣款账户类型，1:支付账户 2:现货账户
`refund_gas_amount`	`string`	退款手续费，只有退到web3有
`refund_fail_reason`	`string`	退款失败原因
`refund_to_gate_uid`	`string`	退款至gate用户uid
`channelId`	`string`	客户渠道名称
`nickName`	`string`	用户昵称
`payerId`	`string`	用户UID
`fromAddress`	`string`	付款地址
`payChannel`	`string`	支付方式: Web3 支付 Gate 支付
`billType`	`string`	账单类型
`goodsName`	`string`	商品名称
`totalRequestAmount`	`string`	订单维度-申请退款金额
`totalRequestCurrency`	`string`	订单维度-申请退款币种
`totalReceiveAmount`	`string`	订单维度-实际到账订单金额
`totalReceiveCurrency`	`string`	订单维度-实际到账订单币种
`refundDetails`	`[] RefundDetailItem`	退款单详情列表

RefundDetailItem 结构:

字段名	类型	说明
`transactionId`	`string`	支付流水订单号
`transactTime`	`int64`	支付时间
`payChannel`	`string`	支付渠道
`status`	`string`	支付状态
`amount`	`string`	退款金额
`currency`	`string`	退款币种
`chain`	`string`	网络信息
`address`	`ChainItem`	商户收款地址
`hash`	`string`	交易hash
`remark`	`string`	备注
`billType`	`string`	账单类型

退款单Status枚举值：

值	解释
`PENDING`	订单待支付
`PROCESS`	订单处理中
`CHECK`	订单审核中
`SUCCESS`	退款成功
`FAIL`	退款失败

请求示例代码

curl --location --request GET 'https://openplatform.gateapi.io/v2/pay/refund/details?refundRequestId=re8350538543' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

返回示例

{
    "code": "000000",
    "data": {
        "refundRequestId": "re8350538543",
        "gateRefundId": "55600765439311884",
        "refundId": "re8350538543",
        "orderId": "55600765439311876",
        "merchantTradeNo": "55600765439311875",
        "createTime": 1763341682831,
        "transactTime": 1763341682885,
        "transactionId": "55600765439311884",
        "txHash": "",
        "orderAmount": "1",
        "orderCurrency": "USDT",
        "requestAmount": "1",
        "requestCurrency": "USDT",
        "amount": "1",
        "currency": "USDT",
        "status": "SUCCESS",
        "remark": "test refund",
        "refund_style": 2,
        "refund_pay_channel": 1,
        "refund_address": "",
        "refund_chain": "",
        "refund_bear_type": 1,
        "refund_amount_type": 0,
        "refund_account_type": 0,
        "refund_gas_amount": "0",
        "refund_fail_reason": "",
        "refund_to_gate_uid": 22178618,
        "channelId": "test",
        "nickName": "test",
        "payerId": 22178618,
        "fromAddress": "",
        "payChannel": "qrcode_pay",
        "billType": 2,
        "goodsName": "test",
        "totalReceiveAmount": "1",
        "totalReceiveCurrency": "USDT",
        "totalRequestAmount": "1",
        "totalRequestCurrency": "USDT",
        "refundDetails": [
          {
            "address": "0xCfbC0ac54223eC44c5a4987c447A8C460BdB9e7b",
            "amount": "1",
            "billType": 2,
            "chain": "BSC",
            "currency": "USDT",
            "hash": "",
            "payChannel": "qrcode_pay",
            "status": "SUCCESS",
            "transactTime": 1763341682866,
            "transactionId": "55600765439311884"
          }
        ]
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

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

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

其中Gate支付的消息通知见4.1 订单状态变更异步通知，支付成功状态订单的支付金额看oderAmount。

收银台中地址支付的消息通知见4.3 消息结构，链上有效期内确认中的金额看waitAmountOnChain，链上有效期内确认完毕的金额看doneAmountOnChain。

# 5. 常见问题

# Q:订单有效期为多久

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

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

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

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

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

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

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

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

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

Last Updated: 2/9/2026, 12:11:01 PM