• Python
  • Golang
  • Java

# 1. The Introduction of QR-code Payments

Users can pay by scanning the QR codes provided by Gate and displayed by the 3rd party merchants.

  • After 3rd party merchants register merchant information and complete the technical integration with Gate Pay, merchants can obtain different QR codes for different product orders, and will display the QR codes for users to scan to pay for the orders
  • The users use the Gate APP to scan the QR codes
  • The users confirm the payment by entering the payment password and clicking the "Confirm" button
  • After the payment is completed, Gate will notify the merchants and the users of the payment status

# 2. QR-code Payments

# 2.1 Flow Chart

Please note that:

  • The HTTPS protocol is used to transmit transaction data to prevent data from being intercepted and decrypted.
  • Use api_secret as data signature to clarify the transaction identity and ensure the correctness and uniqueness of the transaction subject.

# 2.2 API Calling Process

  1. The merchant system calls (/v1/pay/transactions/native QR code ordering interface) to obtain the QR code string qr_code of the order. The developer needs to use the QR code generation tool to generate the final order QR code pictures.
  2. Initiate a polling to obtain the payment result: After waiting for 5 seconds, call the order status query interface (/v1/pay/order/query), and obtain the payment result through the merchant order number (merchantTradeNo) passed in during payment. If the returned result is to wait for the user to pay (PENDING), await another 5 seconds and continue querying until the exact payment result is returned (the order is successfully paid or the order is closed)
  3. In addition to active polling, when the order payment is completed, the merchant can also obtain the payment result returned by the Gate Pay server by setting an asynchronous notification (notify_url).

# 3. Order Placement

# 3.1 Order Placement

  • Data type: JSON (content-type: application/json)
  • Request method: POST
  • Path: /v1/pay/transactions/native
  • Verification method: Merchant signature verification

request body type:

Field Name Type Required Description
merchantTradeNo string Yes Merchant Order Number
currency string Yes Order Currency in uppercase, such as USDT, BTC, etc.
orderAmount string Yes Order Amount, with up to 6 decimal places, ranging from 0.000001 to 50000.
env Env type Yes Transaction Source
goods Goods Type Yes Product Description
orderExpireTime int64 No Order Expiration Time in UTC Timestamp, with millisecond precision. The default is 1 hour if not set, and the maximum expiration time is 1 hour.
returnUrl string No The URL to return to after a successful payment. Maximum length of 256 characters.
cancelUrl string No The URL to return to after a failed payment. Maximum length of 256 characters.
channelId string No Client Name.

Env type

Field Name Type Required Description
terminalType string Yes Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS

Goods type

Field Name Type Required Description
goodsName string Yes Product name, up to 160 characters
goodsDetail string No Product description, up to 256 characters
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

data type:

Field Name Type Required Description
prepayId string Yes The ID of the pre-order created successfully.
terminalType string Yes Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS.
expireTime int64 Yes Order expiration time in UTC timestamp with millisecond precision. The default is 1 hour if not set, and the maximum expiration time is 1 hour.
qrContent string Yes The order QR code (valid for 1 hour) returned as a string. Developers need to generate the QR code image themselves based on the content.

Example of Requests:

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: 1674117221032' \
--header 'x-GatePay-Nonce: 7436636664' \
--header 'x-GatePay-Signature: 11e658cf6b09d917caf9d4bb6ec4493431c55f066a694e58a5571a4a1a114ebc2011d346f340e54a5a2e2edaa172e907742fbdc99b94d009dade4b551daabd07' \
--data-raw '{
    "MerchantTradeNo": "118223456797",
    "currency":"USDT",
    "orderAmount":"1.9",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1674118228000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId": "123456"
}'

Example of Response:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50984376880599040",
        "terminalType": "APP",
        "expireTime": 1674118228000,
        "qrContent": "http://openplatform.gate.io/qr/amaA9duknMfGKvM5H77Q0STgoTgVPmbPyuPDzlFvJO8="
    }
}

# 4. Error Code

Error Code Description Solution
400000 Invalid request parameters Check the format of the request data.
400002 Signature verification failed Check if the merchant signature is correct.
400003 Request timestamp timeout Check the timestamp field in the request head.
400007 Unsupported media type Check the supported media type for the API.
400603 Order timeout Check if the order has expired.
400621 Incorrect payment amount Check the requested amount.
400620 Duplicate payment for order Check if the merchant order number has been submitted twice.
500008 Merchant not found Check if the requested merchant ID is correct.
500100 Payment QR code has expired Place a new order to generate a new QR code.
500101 Duplicate payment for QR code Check the order status.

# 5. FAQ

# Q: How long is the QR code generated by the pre-order interface valid for？

A：The user can specify the expiration time, and the maximum and default validity period is one hour.

Last Updated: 6/11/2025, 9:38:28 AM