Web pay operates in a process like that: purchasers scan and confirm to buy goods or services on merchant webpages, confirm to pay with GatePay, and then the browser automatically jumps to the GatePay payment component to complete the payment.
The users place an order on the merchant website, and then the page would jump to the GatePay payment page.
The users enter the payment password to complete the payment. Once it is completed, the page would display the payment result.
Scan code to pay with GateApp
GateApp QR code
Note:
Jump to the Web payment component according to the location field actually returned by the order creation interface (/v1/pay/transactions/native
). Users can directly jump to the said address returned.
If the jumping is successful, the following interface will be displayed:
The below is an example of the format
GET https://microapp.gateio.services/webpay/?prepayid=50913213697495040
For the order asynchronous notification API, please refer to the Chapter API list.
JSON (content-type: application/json)
POST
/v1/pay/transactions/native
Field Name | Type | Required | Description |
---|---|---|---|
merchantTradeNo | string | Yes | Merchant order number, up to 32 bytes |
currency | string | Yes | Order currency, uppercase, such as USDT, BTC, etc. |
orderAmount | string | Yes | Order amount, ranging from [0.0001, 500000] |
actualCurrency | string | No | The actual currency requested by the merchant for settlement. Use this field to specify the actual incoming currency if the settlement currency requested by the merchant is different from the order currency. |
env | Env type | Yes | Transaction source APP, WEB, WAP, MINIAPP, OTHERS |
goods | goods type | Yes | Description of goods |
orderExpireTime | int64 | No | Order expiration time, UTC timestamp in milliseconds. If not set, it defaults to 1 hour, with a maximum expiration time of 1 hour. |
returnUrl | string | No | The return URL for the order after successful payment, up to 256 characters long. |
cancelUrl | string | No | The return URL for the order after payment failure, up to 256 characters long. |
channelId | string | No | Client Name. |
Env type
Field Name | Type | Required | Description |
---|---|---|---|
terminalType | string | Yes | Transaction source. Available values: APP, WEB, WAP, MINIAPP, OTHERS. |
Goods type
Field Name | Type | Required | Description |
---|---|---|---|
goodsName | string | Yes | Goods name, up to 160 characters. |
goodsDetail | string | No | Goods description, up to 256 characters. |
Response fields
Field Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | SUCCESS or FAIL |
code | string | Yes | Error code |
data | data type | No | Refund information |
errorMessage | string | No | Error message, if any |
data type:
Field Name | Type | Required | Description |
---|---|---|---|
terminalType | string | Yes | Transaction source. Available values: APP, WEB, WAP, MINIAPP, OTHERS. |
expireTime | int64 | Yes | Order expiration time in milliseconds. If not set, it defaults to 1 hour, with a maximum expiration time of 1 hour. |
qrContent | string | Yes | The order QR code (valid for 1 hour) returned as a string. Developers need to use tools to generate the QR code image based on the content. |
location | string | Yes | The Web payment component redirect URL after creating the order. |
Example of request (when the merchant's deposit currency is the same as the order currency):
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"
}'
Response for request:
{
"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"
}
}
Example of request (when the merchant's actual deposit currency is the same as the order currency, and the actual pay currency is specified in the parameter):
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"
}'
Response for request:
{
"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"
}
}
Interface description: When the merchant's order is canceled, the merchant can initiate a request to GatePay to close an unpaid order. The unclosed order can only wait to go expire.
JSON (content-type: application/json)
POST
/v1/pay/order/close
Attribute Name | Data Type | Required | Description |
---|---|---|---|
merchantTradeNo | string | No | Merchant order number, no more than 32 bytes |
prepayId | string | No | Only one of prepayId and merchantTradeNo needs to be provided |
Response type:
Attribute Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | SUCCESS or FAIL |
code | string | Yes | Error code |
data | close result type | Yes | Closing results |
errorMessage | string | No | Error information |
close result type
Attribute | Type | Required | Description |
---|---|---|---|
result | string | Yes | SUCCESS or FAIL |
Exapmle of response
{
"status": "SUCCESS",
"code": "000000",
"data": {
"result": "SUCCESS"
},
"errorMessage": ""
}
In order to facilitate merchants to synchronize order information, GatePay provides a query interface for querying order status
JSON (content-type: json)
POST
/v1/pay/order/query
Attribute Name | Type | Required | Description |
---|---|---|---|
prepayId | string | No | Prepay information. |
merchantTradeNo | string | No | Merchant order ID. Either the prepay ID or this ID parameter must be provided. |
Response type
Attribute Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | SUCCESS or FAIL |
code | string | Yes | Error code |
data | query order return type | No | Payment order information |
errorMessage | string | No | Error message, if any |
query order return type:
Attribute Name | Type | Required | Description |
---|---|---|---|
prepayId | string | Yes | Prepay ID |
merchantId | int64 | Yes | Gate UID used to apply for a merchant account |
merchantTradeNo | string | Yes | Merchant order ID |
transactionId | string | Yes | Transaction ID |
goodsName | string | Yes | Goods name |
currency | string | Yes | Order currency |
orderAmount | string | Yes | Order amount |
status | string | Yes | Order status |
createTime | int64 | Yes | Prepay creation time in milliseconds |
expireTime | int64 | Yes | Prepay expiration time in milliseconds |
transactTime | int64 | Yes | Payment completion time in milliseconds |
order_name | string | Yes | Order name |
pay_currency | string | Yes | Currency paid by the user |
pay_amount | string | Yes | Amount paid by the user |
expectCurrency | string | No | Revenue currency specified when creating the order. Only returned in the order details with a specified settlement currency by the merchant. |
actualCurrency | string | No | Currency actually settled to the merchant's account by the Gate backend after the order was paid. Only returned in the order details after Gate settles with the merchant. |
actualAmount | string | No | Amount in the currency actually settled to the merchant's account by the Gate backend after the order was paid. Only returned in the order details after Gate settles with the merchant. |
rate | string | Yes | Exchange rate for Convert payment. |
channelId | string | No | Client Name. |
Example of request code
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
Example of response
{
"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"
}
}
Example response for querying the order details of a specified revenue currency that has not been settled:
{
"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",
"channelId": "123456"
}
}
Example response for querying the order details of a specified revenue currency that has been settled:
{
"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"
}
}
Merchants can initiate a refund for an order that has been successfully paid for.
Execution of the refund order will commence after the refund order is created, without a confirmation from the merchant and user. After the refund is completed, the GatePay background will send a notification of the refund result.
Please note: Refunds cannot be canceled, withdrawn, or rolled back.
JSON (content-type: application/json)
POST
/v1/pay/order/refund
Attribute Name | Type | Required | Description |
---|---|---|---|
refundRequestId | string | Yes | Merchant-generated refund request ID. The ID must be unique and no more than 32 characters long. |
prepayId | string | Yes | The ID of the completed payment order. |
refundAmount | string | Yes | The refund amount, which cannot exceed the total order amount. |
refundReason | string | No | The reason for the refund, up to 256 characters long. |
Response
Attribute Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | The status of the response, which can be either SUCCESS or FAIL. |
code | string | Yes | The error code. |
data | refund data type | No | The information of the refund order. |
errorMessage | string | No | The error message. |
refund data type
Attribute Name | Type | Required | Description |
---|---|---|---|
refundRequestId | string | Yes | The ID of the refund order, which is generated by GatePay. |
prepayId | string | Yes | The ID of the prepayment order. |
orderAmount | string | Yes | The amount of the original order. |
refundAmount | string | Yes | The amount requested to be refunded. |
Example of request
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
Example of returned data
{
"status": "SUCCESS",
"code": "000000",
"data": {
"refundRequestId": "156123911",
"prepayId": "1647438500687506",
"orderAmount": "1.91",
"refundAmount": "0.8"
},
"errorMessage": ""
}
JSON (content-type: json)
POST
/v1/pay/order/refund/query
Attribute Name | Type | Required | Description |
---|---|---|---|
refundRequestId | string | Yes | The refund order ID generated by the merchant. |
Response:
属性名 | 类型 | 是否必须 | 说明 |
---|---|---|---|
status | string | 是 | SUCCESS 或者 FAIL |
code | string | 是 | 出错代码 |
data | query refund return type | 否 | 退款单信息 |
errorMessage | string | 否 | 错误信息 |
query refund return type
Attribute Name | Type | Required | Description |
---|---|---|---|
refundRequestId | string | Yes | Merchant-generated refund request ID (must be unique and no more than 32 characters) |
prepayId | string | Yes | ID of the completed payment order |
orderAmount | string | Yes | Order amount |
refundAmount | string | Yes | Refund amount, cannot exceed the total order amount |
refundReason | string | No | Refund reason, up to 256 characters |
Example of request:
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
Example of response
{
"status": "SUCCESS",
"code": "000000",
"data": {
"refundRequestId": "156123911",
"prepayId": "1647557960944",
"orderAmount": "1.91",
"refundAmount": "0.8",
"refundStatus": "SUCCESS"
},
"errorMessage": ""
}
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 | 二维码重复支付 | 请核实订单状态 |