# 1. Product introduction
# 1.1 Features
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.
# 1.2 Example
# 1.2.1 Pay on the payment page
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.
# 1.2.2 Scan code to pay with GateApp
Scan code to pay with GateApp
GateApp QR code
# 2. Main process
Note:
- The users create an order for merchandise at merchant's mall by sending requests to merchant's backend.
- The merchant's backend generates a signature (see Chapter 4 signature algorithm), and requests GatePay to create a pre-pay order interface (/v1/pay/transactions/native).
- After the Gate backend successfully verifies the request parameters and signature, it generates a pre-pay order and returns it to the merchant backend.
- The merchant's backend generates the signature and parameters enabling the jumping to Gate Web payment component (refer to Chapter 4 Signature Algorithm) and returns it to the merchant's Web frontend together with the order information.
- The web frontend will skip to the Gate Web payment component to the online address, which refers to the location field returned from the order creation interface (/v1/pay/transactions/native). If the jumping is successful, the payment information will be displayed and the user can complete the payment by following the instructions.
- The users pay by scanning the QR code with Gate App or pay directly on the Web payment component by entering the password.
- After payment is completed, the payment result will be notified asynchronously to the merchant's backend, and the web payment component will display the payment result when detecting a change in order status.
# 2.1 Redirecting URL and rules for the jumping to web payment component
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.
The below is an example of the format
GET https://microapp.gateio.services/webpay/?prepayid=50913213697495040
If the jumping is successful, the following interface will be displayed：
# 3. Asynchronous notification of order status
- When the order status changes, such as the successful payment of the order, the payment timeout, the cancellation of the order, etc., the GatePay background will send an order status notification to the merchant to the address that is the callback URL provided by the merchant during registration.
- If the notification fails to be delivered due to network issues or other unknown reasons, GatePay background will retry 10 times every 3 seconds. If it still does work, the merchant can obtain the order status by calling the order status query interface.
- When receiving the asynchronous notification, the merchants must verify the signature parameters to ensure the legitimacy of the message.
For the order asynchronous notification API, please refer to the Chapter API list.
# 4. API list
# 4.1 Create a prepay order
- Type of data：
JSON （content-type: application/json） - Request method：
POST - Path:
/v1/pay/transactions/native - Verification method：Merchant signature verification
- Request body content:
| 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. |
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"
}
}
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. |
# 4.2 Close pre-pay order
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.
- Type of data:
JSON (content-type: application/json) - Request method：
POST - PATH:
/v1/pay/order/close - Request body content：
| 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": ""
}
# 4.3 Order Status Inquiry
In order to facilitate merchants to synchronize order information, GatePay provides a query interface for querying order status
- Type of data：
JSON (content-type: json) - Request method：
POST - URL:
/v1/pay/order/query - Request body type
| 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"
}
}
# 4.4 Refund interface
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.
- Type of data:
JSON (content-type: application/json) - Request method：
POST - PATH:
/v1/pay/order/refund - Request body content：
| 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": ""
}
# 4.5 Query refund order
- Type of data：
JSON (content-type: json) - Request method：
POST - PATH:
/v1/pay/order/refund/query - Request body type
| 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": ""
}
# 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 | 二维码重复支付 | 请核实订单状态 |