• Python
  • Golang
  • Java

# 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

  1. The users place an order on the merchant website, and then the page would jump to the GatePay payment page.


  2. 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

  1. Scan code to pay with GateApp

  2. GateApp QR code


# 2. Main process

Note:

  1. The users create an order for merchandise at merchant's mall by sending requests to merchant's backend.
  2. 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).
  3. After the Gate backend successfully verifies the request parameters and signature, it generates a pre-pay order and returns it to the merchant backend.
  4. 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.
  5. 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.
  6. The users pay by scanning the QR code with Gate App or pay directly on the Web payment component by entering the password.
  7. 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.

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

# 3. Asynchronous notification of order status

  1. 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.
  2. 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.
  3. 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.

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"
    }
}

# 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 二维码重复支付 请核实订单状态