# 1. 产品介绍

# 1.1 产品特色

Web端支付是指商户在电脑网页展示商品或服务，用户在商户页面确认使用GatePay支付时，浏览器自动跳转GatePay支付组件完成付款的支付产品。

# 1.2 使用示例

# 1.2.1 在支付页面支付

在商户网站选择商品下单后，跳转到GatePay支付页面，并支付
进行支付，输入支付密码和支付结果展示

# 1.2.2 在Web支付组件使用GateApp扫码支付

在Web支付组件使用GateApp扫码支付
App扫码支付和支付结果界面

# 2. 主要流程

备注:

用户在商户商城选择商品后，请求商户后端创建订单。
商户后端生成签名(参考章节4签名算法)，请求GatePay创建预订单接口( /v1/pay/transactions/native)。
Gate后端验证请求参数和签名成功后生成支付预订单，并返回给商户后端。
商户后端生成跳转Gate Web支付组件签名和参数(参考章节4签名算法)并和预订单信息一起返回给商户Web前端。
Web前端跳转到Gate Web支付组件，线上跳转地址为创建订单接口( /v1/pay/transactions/native)返回location字段，跳转成功后显示支付信息并等待用户支付。
用户在Gate App扫码支付或直接在Web支付组件密码支付。
支付后订单支付结果异步通知给商户后端，并且web支付组件监控到订单状态改变后显示支付结果。

# 2.1 跳转Web支付组件跳转URL及规则

根据创建订单接口(/v1/pay/transactions/native)实际返回的location字段跳转到Web支付组件,商户根据返回直接跳转到改地址即可。

URL格式示例

GET https://microapp.gateio.services/webpay/?prepayid=50913213697495040

跳转成功会显示如下界面：

# 3. 订单状态异步通知

在订单状态发生改变时，比如，支付成功，超出支付时间，订单取消等操作，GatePay后台会向商户发送订单状态通知。通知地址是商户注册时提供的callback url。
如果由于网络或者其他未知原因导致通知失败，GatePay后台会每隔3秒重试10次。如果重试也失败，商户可以通过调用订单状态查询接口获取订单状态。
商户接手到的异步通知信息，必须校验签名参数来验证消息合法性。

订单异步通知API请参考章节API列表。

# 4. API列表

# 4.1 创建预付单

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

字段名	类型	是否必须	说明
`merchantTradeNo`	`string`	是	商户订单号，不大于32字节
`currency`	`string`	是	订单币种，大写形式，如USDT、BTC等
`orderAmount`	`string`	是	订单金额，订单金额范围在[0.0001,500000]
`actualCurrency`	`string`	否	商户实际要求入账的币种，如果商户要求入账币种与订单币种不一致，可使用此字段指定实际收入币种
`env`	`Env type`	是	交易来源APP、WEB、WAP、MINIAPP、OTHERS
`goods`	`goods type`	是	商品说明
`orderExpireTime`	`int64`	否	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
`returnUrl`	`string`	否	订单支付成功后返回跳转地址，最长256字符
`cancelUrl`	`string`	否	订单支付失败后返回跳转地址，最长256字符
`channelId`	`string`	否	客户名称

Env type

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

Goods type

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

请求示例(商户实际收入币种与订单币种一致):

curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/transactions/native' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: zb6WUrBDZlRAT7qz' \
--header 'X-GatePay-Timestamp: 1674878689495' \
--header 'x-GatePay-Nonce: 3525756760' \
--header 'x-GatePay-Signature: 8a5b6df55fb3b1415a284311693c34e5510c3db110f949e33290e658f9c20064b3fd8613c5c264f54e9192ca342a2e943c3e0beeb4c3a9d2208d208333029c38' \
--data-raw '{
    "MerchantTradeNo": "118223456797",
    "currency":"USDT",
    "orderAmount":"1.9",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1660204248000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId":"123456"
}'

请求响应:

{
    "status":"SUCCESS",
    "code":"0",
    "errorMessage":"",
    "data":{
        "prepayId":"50913213697495040",
        "terminalType":"APP",
        "expireTime":1674100394000,
        "qrContent":"http://openplatform.gate.io/qr/AjQHJ56mDQ26dtx5ftspl9usV9tlIA8iom35toXhX7Y=",
        "location":"https://114.55.238.130:13555/webpay?prepayid=50913213697495040"
    }
}

请求示例(商户实际收入币种与订单币种一致，在参数中指定实际营收币种):

curl --location --request POST '47.99.158.63:8201/v1/pay/transactions/native' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: zb6WUrBDZlRAT7qz' \
--header 'X-GatePay-Timestamp: 1675665299208' \
--header 'x-GatePay-Nonce: 5966763714' \
--header 'x-GatePay-Signature: 5495750ff0085637884ce8e23fd54caebbacaa318f7a597e03dad1abc418e382b4a964c6e319bacea1dc78cb7cb3e49938b8fe0c6cc9a84d210705137f1d57a9' \
--data-raw '{
    "MerchantTradeNo": "118223456712203",
    "currency":"USDT",
    "orderAmount":"1",
    "actualCurrency": "USDT",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1675666173000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId":"123456"
}'

请求响应:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "57477481708392448",
        "terminalType": "APP",
        "expireTime": 1675666173000,
        "qrContent": "http://openplatform.gate.io/qr/2Z29MDvtqIAeN5VuFLMK6IjEFBmv4V8bsKdDDWu2gLs=",
        "location": "https://114.55.238.130:13555/webpay?prepayid=57477481708392448"
    }
}

响应字段

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

date字段:

字段名	类型	是否必须	说明
`terminalType`	`string`	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
`expireTime`	`int64`	是	订单过期时间，单位毫秒。不设置时默认为1小时，最大过期时间为1小时
`qrContent`	`string`	是	订单二维码（有效时间 1 小时）以字符串的格式返回，开发者需要自己使用工具根据内容生成二维码图片。
`location`	`string`	是	创建订单后，Web支付组件跳转地址

# 4.2 预付单关闭

接口说明：当商户端订单被取消时，商户可以主动发起请求要求GatePay关闭一个未支付的订单，如果一个订单号不被关闭，只能等待过期。

请求类型: JSON (content-type: application/json)
请求方法：POST
PATH: /v1/pay/order/close
请求体内容：

属性名	类型	是否必须	说明
`merchantTradeNo`	`string`	否	商户订单号，不大于32字节
`prepayId`	`string`	否	prepayId merchantTradeNo 只需提供一个

返回类型

属性名	类型	是否必须	说明
`status`	`string`	是	SUCCESS 或者 FAIL
`code`	`string`	是	出错代码
`data`	`close result type`	是	关闭结果
`errorMessage`	`string`	否	错误信息

close result type

属性名	类型	是否必须	说明
`result`	`string`	是	SUCCESS 或者 FAIL

返回示例

{
    "status": "SUCCESS",
    "code": "000000",
    "data": {
        "result": "SUCCESS"
    },
    "errorMessage": ""
}

# 4.3 订单状态查询

为方便商户同步订单信息，GatePay提供了查询接口用于查询订单状态

请求类型：JSON (content-type: json)
请求方法：POST
URL: /v1/pay/order/query
请求体类型

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

请求回应类型

属性名	类型	是否必须	说明
`status`	`string`	是	SUCCESS 或者 FAIL
`code`	`string`	是	出错代码
`data`	`query order return type`	否	支付订单信息
`errorMessage`	`string`	否	错误信息

data参数：

属性名	类型	是否必须	说明
`prepayId`	`string`	是	预付单id
`merchantId`	`int64`	是	用于申请商户账号的Gate UID
`merchantTradeNo`	`string`	是	商户订单号
`transactionId`	`string`	是	交易id
`goodsName`	`string`	是	商品名称
`currency`	`string`	是	订单币种
`orderAmount`	`string`	是	订单金额
`status`	`string`	是	订单状态
`createTime`	`int64`	是	预付单创建时间，单位毫秒
`expireTime`	`int64`	是	预付单过期时间，单位毫秒
`transactTime`	`int64`	是	支付完成时间，单位毫秒
`order_name`	`string`	是	订单名称
`pay_currency`	`string`	是	用户实际支付币种
`pay_amount`	`string`	是	用户实际支付金额
`expectCurrency`	`string`	否	商家创建订单时，指定营收币种，注：仅在商户指定结算币种的订单详情中返回
`actualCurrency`	`string`	否	订单支付完成后，Gate后台实际结算到商户账户的币种，注：仅在订单Gate结算给商户后才在订单详情中返回
`actualAmount`	`string`	否	订单支付完成后，对应Gate后台实际结算到商户账户的币种的金额，注：仅在订单Gate结算给商户后才在订单详情中返回
`rate`	`string`	是	闪兑支付时的汇率
`channelId`	`string`	否	客户名称

请求代码示例

  curl -X POST -H "Content-Type:application/json" \
        -H "X-GatePay-Certificate-ClientId: aa721ba2-5bad-55e5-b3f9-43f9cbe6d814" \
        -H "x-gateio-payment-timestamp: 1647556285603" \
        -H "x-gateio-payment-nonce: OBBHcyeIQn" \
        -H "x-gateio-payment-signature: 1f020e1ee70a7ced14de42f4293592d43f8a74eab5ba4c3771dc6d215278d889fd0ecd398c1026a003b1351752b34c24cd8288afa7ff7552ca06a2aea992a897" \
        -d '{"merchantTradeNo": "56236"}' https://openplatform.gateapi.io/v1/pay/order/query

查询非指定营收币种订单详情，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50620368071692288",
        "merchantId": 10002,
        "merchantTradeNo": "4379824792349592345",
        "transactionId": "",
        "goodsName": "NFT",
        "currency": "GT",
        "orderAmount": "0.1",
        "status": "EXPIRED",
        "createTime": 1674030436229,
        "expireTime": 1663054706000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#4379824792349592345",
        "pay_currency": "",
        "pay_amount": "0",
        "rate": "0",
        "channelId":"123456"
    }
}

查询指定营收币种订单详情，未结算，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56335302571069440",
        "merchantId": 10002,
        "merchantTradeNo": "118223456798",
        "transactionId": "",
        "goodsName": "NF2T",
        "currency": "USDT",
        "orderAmount": "1.9",
        "status": "EXPIRED",
        "createTime": 1675392982792,
        "expireTime": 1675396480000,
        "transactTime": 0,
        "order_name": "MiniApp-Payment#118223456798",
        "pay_currency": "",
        "pay_amount": "0",
        "expectCurrency": "BTC",
        "rate": "0"
    }
}

查询指定营收币种订单详情，已结算，响应示例

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "56416503889661952",
        "merchantId": 10002,
        "merchantTradeNo": "1182234567119",
        "transactionId": "56416503889661952",
        "goodsName": "NF2T",
        "currency": "GT",
        "orderAmount": "1",
        "status": "PAID",
        "createTime": 1675412342695,
        "expireTime": 1675414420000,
        "transactTime": 1675412385904,
        "order_name": "MiniApp-Payment#1182234567119",
        "pay_currency": "BTC",
        "pay_amount": "1",
        "expectCurrency": "USDT",
        "actualCurrency": "USDT",
        "actualAmount": "1",
        "rate": "1",
        "channelId":"123456"
    }
}

# 4.4 退款接口

商户可以针对一个已成功支付的订单发起退款。退款执行并不需要付款商户和用户确认。退款订单创建后就会开始安排执行。退款成功后，GatePay后台会发送退款结果通知。请注意：退款不可以取消、撤回、回滚。

请求类型: JSON (content-type: application/json)
请求方式：POST
PATH: /v1/pay/order/refund
请求体内容：

属性名	类型	是否必须	说明
`refundRequestId`	`string`	是	商户生成的退款单id。退款单id必须唯一，不大于32字符
`prepayId`	`string`	是	已完成支付的订单Id
`refundAmount`	`string`	是	退款金额，不能超过订单总金额
`refundReason`	`string`	否	退款原因，最长256字符

响应

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

refund data type

属性名	类型	是否必须	说明
`refundRequestId`	`string`	是	退款单id，GatePay生成
`prepayId`	`string`	是	预付单id
`orderAmount`	`string`	是	订单金额
`refundAmount`	`string`	是	申请退款金额

请求示例代码

curl -X POST -H "Content-Type:application/json" \
        -H "X-GatePay-Certificate-ClientId: aa721ba2-5bad-55e5-b3f9-43f9cbe6d814" \
        -H "x-gateio-payment-timestamp: 1647556285603"
        -H "x-gateio-payment-nonce: OBBHcyeIQn"
        -H "x-gateio-payment-signature: 1f020e1ee70a7ced14de42f4293592d43f8a74eab5ba4c3771dc6d215278d889fd0ecd398c1026a003b1351752b34c24cd8288afa7ff7552ca06a2aea992a897" \
        -d '{"refundRequestId": "156123911", "prepayId": "1647438500687506", "refundAmount": "0.8"}' 
https://openplatform.gateapi.io/v1/pay/order/refund

返回示例

{
"status": "SUCCESS",
"code": "000000",
"data": {
    "refundRequestId": "156123911",
    "prepayId": "1647438500687506",
    "orderAmount": "1.91",
    "refundAmount": "0.8"
},
"errorMessage": ""
}

# 4.5 查询退款单

请求类型：JSON (content-type: json)
请求方法：POST
PATH: /v1/pay/order/refund/query
请求体类型

属性名	类型	是否必须	说明
`refundRequestID`	`string`	是	商户侧生成的退款单id

响应:

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

query refund return type

属性名	类型	是否必须	说明
`refundRequestID`	`string`	是	商户退款单id，有商户后端生成保证唯一
`prepayId`	`string`	是	订单id，GatePay后端生成
`orderAmount`	`string`	是	订单金额
`refundAmount`	`string`	是	退款金额
`refundStatus`	`string`	是	退款单状态 SUCCESS:退款成功 FAIL退款失败

请求代码示例：

curl -X POST -H "Content-Type:application/json" \
    -H "X-GatePay-Certificate-ClientId: aa721ba2-5bad-55e5-b3f9-43f9cbe6d814" \
    -H "x-gateio-payment-timestamp: 1647556285603" \
    -H "x-gateio-payment-nonce: OBBHcyeIQn" \
    -H "x-gateio-payment-signature: 1f020e1ee70a7ced14de42f4293592d43f8a74eab5ba4c3771dc6d215278d889fd0ecd398c1026a003b1351752b34c24cd8288afa7ff7552ca06a2aea992a897" \
    -d '{ "refundRequestId": "156123911"}'  https://openplatform.gateapi.io/v1/pay/order/refund/query

回应示例

{
   "status": "SUCCESS",
   "code": "000000",
   "data": {
      "refundRequestId": "156123911",
      "prepayId": "1647557960944",
      "orderAmount": "1.91",
      "refundAmount": "0.8",
      "refundStatus": "SUCCESS"
   },
   "errorMessage": ""
}

# 5. 常见错误码

http状态码	错误码	描述	解决方案
`500`	`300000`	系统错误	系统异常，请用相同参数重新调用
`500`	`300001`	内部错误	系统异常，请用相同参数重新调用
`500`	`400000`	未知错误	系统异常，请用相同参数重新调用
`200`	`400001`	请求参数格式错误	检查请求数据参数和格式
`200`	`400002`	签名校验失败	检查商户签名是否正确
`200`	`400003`	请求时间戳超时	检查请求head里的时间戳字段
`200`	`400007`	不支持的media type	查看接口设置的media type
`200`	`400020`	签名随机数错误	请检查随机数是否为空
`200`	`400201`	商户订单号重复	请核实商户订单号是否重复提交
`200`	`400202`	订单不存在	请检查订单是否发起过交易或订单号是否正确
`200`	`400203`	商户号不存在	请检查商户号是否正确
`200`	`400204`	订单状态不正确	检查订单是否过期，取消被关闭状态，可调查询接口
`200`	`400304`	退款单ID不存在	检查请求的退款单ID
`200`	`400603`	订单超时	请核实订单是否过期
`200`	`400604`	退款关联交易单无效	请检查退款交易单是否为完成状态
`200`	`400605`	支付账户余额不足	支付账户余额不足
`200`	`400607`	退款次数太多	退款次数大于限制
`200`	`400608`	退款金额异常	请检查退款金额
`200`	`400620`	订单重复支付	请核实商户订单号是否重复提交
`200`	`400621`	错误的支付金额	检查请求金额
`200`	`400622`	汇率波动导致币种兑换失败	可以重试在次申请
`200`	`400623`	不支持币种支付	请检查支付币种
`200`	`400624`	无效订单状态通知地址	检查商户提供回调地址是否有效
`200`	`500008`	未找到对应商户	检查请求商户ID是否正确
`200`	`500100`	支付二维码过期	重新下单生成新二维码
`200`	`500101`	二维码重复支付	请核实订单状态

Last Updated: 5/23/2025, 12:54:07 PM