# changelog

    # v1.0.0

    2023-01-10
Address Payment Integration Guide Version 1.0

    # 1. Features

    The address payment supports users to trade with Gate merchants via any wallet assets if they have not owned a Gate account.

    Gate merchants can query the supported chains and addresses for a specific currency, and display the supported address to the user.

    The user transfers assets to the designated address through the three-party wallet.

    The next step is to wait for the chain to confirm the asset transfer. When it is confirmed, Gate will update the order status, and asynchronously transfer the asset to the merchant's account

    Then, the status of the address payment order changes, and currency will arrive in the merchant's account, and the corresponding notification is sent to the merchant's registered callback address.

    # 2. Address payment

    # 2.1 Flow chart

    地址支付流程图V2

    Note:

    1. The user enters the order interface of the merchant's client, and the merchant's backend queries the chains supported by the currency of the order placed and returns the query result.
    2. The user selects the target chain of the transfer and clicks “pay now”.
    3. Generate a pre-payment order in the merchant background and Gate payment background. When the Gate background generates a pre-order, bind an available chain wallet address according to the chain selected by the order.
    4. Return the order details to the merchant background, which will display the wallet address corresponding to the order to the user.
    5. The user initiates the transfer of assets to the order address through the three-party wallet.
    6. When the Gate chain service background detects the user payment, it will update the order status based on the order payment information and order expiration time.
    7. Send an order status change information to the merchant's background (note: no matter whether the order is completed or expired, no transfer to the merchant's payment account is made at this time)
    8. The Gate payment background continues to monitor the payment status of the completed order on the chain. After all the payment records on the chain are confirmed, the corresponding amount will be transferred to the merchant's payment account.
    9. Send the payment arrival notification to the merchant background.

    # 2.2 Address payment sequence diagram

    # 2.2.1 Non-convert address payment sequence diagram

    地址支付时序图V2

    # 2.2.2 Sequence diagram of convert address payment

    闪兑地址支付时序图

    Remark:

    • Compared with non-convert payment, convert payment has one more step to query the payment currencies that are supported for the conversion of the payment order.
    • The supported payment currency includes the order currency itself. If the order currency is selected as the payment currency, the order will be determined to be a non-convert payment order.

    # 3. Payment arrival

    # 3.1 Asynchronous payment

    # 3.1.1 Definition

    At the completion of the payment order (payment succeeds or fails), the merchant will not receive the relevant account immediately but will experience a delay in receiving the amount.

    # 3.1.2 Convert payment order

    Finished at a successful payment： Convert the user's payment currency into the order currency in the corresponding amount, and deposit it into the merchant's payment account

    Finished at a payment failure： The users' payment amount will be kept in their Gate account, and will not be converted and deposited to the merchant's payment account.

    # 3.2 Delayed payment

    # 3.2.1 Definition

    When the payment record whose on-chain broadcast occurs after the completion of the order or after the validity period of the order, a delayed payment occurs.

    # 3.2.2 Non-convert payment order

    Deposit the user's payment funds to the merchant's payment account

    # 3.2.3 Convert payment order

    The users' payment funds remain in their Gate’s account, and will not be deposited to the merchant's payment account

    # 3.3 Instant Payment

    # 3.2.1 Definition

    Instant payment means once a successful payment is detected on-chain, the amount will be credited to the merchant’s account.

    # 3.2.2 Non-Convert Payment Order

    Before an order expires, for each payment confirmed on-chain, the amount will be credited to the merchant’s account.

    # 4. Notification

    # 4.1 Circumstances for sending messages to merchants

    • The order status changes from the “created” to the “payment completed”.
    • The order status changes from “created” to “expired”.
    • The user pays a sufficient amount within the validity period, the order has not been confirmed until the expiration date, so the order status becomes “process”.
    • Before an order is finished (expired or completed), every time a successful payment is detected, Gate Pay will transfer the corresponding amount to the user’s Payment Account. Once the total payment amount reaches the order amount before it expires, the order status will be changed to “Completed”.
    • After the order is completed, the order address detects the arrival of a new payment, and transfers the amount to the merchant's payment account after confirmation.
    • After the order is completed, the convert payment order address detects the arrival of a new payment.

    # 4.2 Address payment message enumeration value

    BizType

    Value Description
    PAY_ADDRESS This is a notification of an address payment order.
    TRANSFER_ADDRESS Notification of transferring funds to the merchant via address payment.
    RECEIVED_CONVERT_DELAY_ADDRESS The address payment order detects a new delayed arrival record and notifies the merchant, but does not recharge it to the merchant payment account.

    # 4.3 Message structure

    # 4.3.1 Order Status Change Notification

    Notification of status change of non-convert address payment order:

    Field Name Type Description
    bizType string Specifies the type of notification, see the BizType table below.
    bizId string The ID of the order.
    bizStatus string Refer to BizStatus.
    client_id string The client_id of the merchant who created the order.
    data content The content of the message.

    BizStatus

    Value Explanation
    PAY_SUCCESS Payment successful
    PAY_ERROR An error occurred during payment
    PAY_CLOSE Order expired, Payment closed.
    PAY_EXPIRED_IN_PROCESS A special status of address payment. If the amount paid by the user is greater than or equal to the order amount before the order expires, but there is payment pending confirmation, the order will be in an intermediate status named PROCESS.
    PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION Address payment failed due to exchange rate fluctuations in convert.

    content

    Field Name Type Description
    merchantTradeNo string Merchant trade number
    productType string goodsType when creating the order
    productName string GoodsName when creating the order
    tradeType string terminalType when creating the order
    goodsName string GoodsName when creating the order
    terminalType string terminalType when creating the order
    currency string Order currency
    orderAmount string Order amount
    transactionId string Transaction ID
    waitAmountOnChain string Waiting for confirmation on-chain within the effective period
    doneAmountOnChain string The amount confirmed during the validity period on the chain
    payerId int64 UID of the paying user
    createTime int64 Order creation time
    channelId string Client Name.
    chain string Network name
    address string Collection address

    Notification of status change of non-convert address payment order, for example:

    {
    "bizType": "PAY_ADDRESS", 
    "bizId": "1666751129271968", 
    "bizStatus": "PAY_CLOSE", 
    "client_id": "836e1131-fb3d-4648-8b04-bd29c46596ba",  
    "data": "{\"merchantTradeNo\":\"1000220221026006\",\"productType\":\"\",\"productName\":\"测试订单20221026006\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"测试订单20221026006\",\"terminalType\":\"MINIAPP\",\"currency\":\"WMHH\",\"totalFee\":\"0.21\",\"orderAmount\":\"0.21\",\"payerId\":10002,\"createTime\":1666751129271,\"transactionId\":\"1666751408050667\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.1\",\"chain\": \"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\", \"channelId\":\"AA\"}" 
}

    Message content:

    {
    "merchantTradeNo": "1000220221026006", 
    "productType": "", 
    "productName": "测试订单20221026006", 
    "tradeType": "MINIAPP",
    "goodsName": "测试订单20221026006",
    "terminalType": "MINIAPP", 
    "currency": "WMHH", 
    "totalFee": "0.21", 
    "orderAmount": "0.21", 
    "payerId": 10002, 
    "createTime": 1666751129271, 
    "transactionId": "1666751408050667", 
    "waitAmountOnChain": "0", 
    "doneAmountOnChain": "0.1",
    "channelId":"123456",
    "chain": "ETH",
    "address": "0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F"
}

    Notification of the status change of the convert address payment order, for example:

    Field Name Type Description
    bizType string Description of the notification type, see BizType table.
    bizId string Order ID.
    bizStatus string Order status, PENDING for processing, PROCESS for payment within the valid period but not yet confirmed on the chain, PAID for successful payment, EXPIRED for expired orders.
    client_id string The merchant client_id that created the order.
    data content Message content.

    content

    Field Name Type Description
    merchantTradeNo string Merchant transaction number.
    productType string Goods type when creating the order.
    productName string Goods name when creating the order.
    tradeType string Terminal type when creating the order.
    goodsName string Goods name when creating the order.
    terminalType string Terminal type when creating the order.
    currency string Currency of the order.
    totalFee string Total amount of the order.
    orderAmount string Order amount.
    payCurrency string Payment currency.
    payAmount string Required payment amount.
    rate string Exchange rate.
    payerId int64 Payer's user ID.
    createTime int64 Time when the order was created, in UTC milliseconds.
    transactionId string Transaction ID.
    waitAmountOnChain string Amount waiting for confirmation on-chain within the effective period.
    doneAmountOnChain string Amount already confirmed on-chain within the effective period.
    transferAmount string Amount transferred to the merchant, corresponding to the order currency. Only available in transfer notifications, empty string in order status change notifications.
    overPay string Amount paid by the user exceeding the required amount in the order. 0 when the order status is not "Paid".
    channelId string Client Name

    Notification of the status change of the convert address payment order, for example:

    {
   "bizType": "PAY_ADDRESS",
   "bizId": "46301072319320064",
   "bizStatus": "PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION",
   "client_id": "ygMRT5SdrGpiISVV",
   "data": "{\"merchantTradeNo\":\"938402023010600017\",\"productType\":\"\",\"productName\":\"USDT_PAY_WMHH_TEST\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"USDT_PAY_WMHH_TEST\",\"terminalType\":\"MINIAPP\",\"currency\":\"USDT\",\"totalFee\":\"2.1\",\"orderAmount\":\"2.1\",\"payCurrency\":\"WMHH\",\"payAmount\":\"0.2142\",\"rate\":\"0.1\",\"payerId\":10002,\"createTime\":1673000635873,\"transactionId\":\"\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.2142\",\"transferAmount\":\"\",\"overPay\":\"0\"}"
}

    Message contents:

    {
   "merchantTradeNo": "938402023010600017",
   "productType": "",
   "productName": "USDT_PAY_WMHH_TEST",
   "tradeType": "MINIAPP",
   "goodsName": "USDT_PAY_WMHH_TEST",
   "terminalType": "MINIAPP",
   "currency": "USDT",
   "totalFee": "2.1",
   "orderAmount": "2.1",
   "payCurrency": "WMHH",
   "payAmount": "0.2142",
   "rate": "0.1",
   "payerId": 10002,
   "createTime": 1673000635873,
   "transactionId": "",
   "waitAmountOnChain": "0",
   "doneAmountOnChain": "0.2142",
   "transferAmount": "",
   "overPay": "0",
   "channelId":"123456"
}

    # 4.3.2 Order funds transfer notification

    Order funds transfer notice:

    Field Name Type Description
    bizType string Describes the notification category, see table BizType.
    bizId string Order ID.
    bizStatus string Refer to BizStatus
    client_id string The client_id of the merchant who created the order.
    data content The message content.

    BizStatus

    Value Explanation
    TRANSFERRED_ADDRESS_IN_TERM When a successful payment for a non-Convert address payment order is detected, the corresponding amount will be deposited into the merchant's Payment Account instantly (transfer received before the order expires).
    TRANSFERRED_ADDRESS_DELAY When a delayed payment for a non-Convert address payment order is detected, the corresponding amount will be deposited into the merchant's Payment Account (transfer received after the order expires).
    CONVERT_ADDRESS_PAY_DELAY Delayed arrival of convert address payment, notifying the merchant but not crediting it to the merchant's payment account.
    TRANSFERRED_ADDRESS_BLOCK Funds successfully received by Gate but held due to risk (not credited)

    content

    Field Name Type Description
    merchantTradeNo string Merchant trade number
    productType string Goods type when creating the order
    productName string Goods name when creating the order
    tradeType string Terminal type when creating the order
    goodsName string Goods name when creating the order
    terminalType string Terminal type when creating the order
    currency string Order currency
    orderAmount string Order amount
    payerId int64 Payer UID
    createTime int64 Order creation time in UTC millisecond timestamp
    transactionId string Transaction ID
    transferAmount string The amount transferred to the merchant. In the delayed payment scenario of the flash payment order, the received amount will still be sent, but there will be no flash payment, and it will not be paid to the merchant. The funds will be reserved on the Gate chain.
    channelId string Client Name
    chain string Network name
    address string Collection address

    Example of order fund transfer notification：

    {
    "bizType": "TRANSFER_ADDRESS",
    "bizId": "1666751407010007",
    "bizStatus": "TRANSFERRED_ADDRESS_IN_TERM",
    "client_id": "",
    "data": "{\"merchantTradeNo\":\"1000220221026006\",\"productType\":\"\",\"productName\":\"测试订单20221026006\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"测试订单20221026006\",\"terminalType\":\"MINIAPP\",\"currency\":\"WMHH\",\"orderAmount\":\"0.21\",\"payerId\":10002,\"createTime\":1666751129271,\"transactionId\":\"1666751408050667\",\"transferAmount\":\"0.21\",\"chain\": \"ETH\",\"address\":\"0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F\"}"
}

    Message contents:

    {
   "merchantTradeNo": "1000220221026006", 
   "productType": "",
   "productName": "测试订单20221026006", 
   "tradeType": "MINIAPP", 
   "goodsName": "测试订单20221026006",
   "terminalType": "MINIAPP", 
   "currency": "WMHH",
   "orderAmount": "0.21", 
   "payerId": 10002, 
   "createTime": 1666751129271,
   "transactionId": "1666751408050667",
   "transferAmount": "0.21",
   "channelId": "123456",
   "chain": "ETH",
   "address": "0xfb8Cdb7da4A1C3fF56Dc7a5d78c8228711E9028F"
}

    # 5. FAQ

    # Q:After the user transfers funds to the chain, why can't the transfer record be found in the order details?

    A：Since the blockchain is a distributed system, it takes time for the chain to perform packaging and broadcasting after the user initiates the transfer on the chain. As a result, there is a delay in the Gate payment background receiving the user's transfer instruction.

    # Q:Why does the merchant’s account receive no amount when the order shows it has been paid up?

    A：In the address payment business, the user may initiate multiple transfers for the same order. When the order expires or is completed, there may still be some records on the chain that have not been confirmed. The Gate payment background will transfer the funds equal to the amount received to the user's payment account only when all the payment records on the chain corresponding to the order are confirmed (success or failure)

    # Q:Why is the order categorized as expired when the user pays a sufficient amount within the validity period of the order?

    A：After the user transfers funds to the chain, the Gate chain system records the transfer time as the time when the packaging is completed on the chain, which is rather uncontrollable, and thus may cause the order to be recorded as expired.

    # Q: How to determine how much funds an order received through notifications?

    A: The analysis depends on specific scenarios:

    1. Insufficient payment within validity period:

      • Fund arrival notification: bizStatus = TRANSFERRED_ADDRESS_IN_TERM, received amount is transferAmount. (Need to accumulate all payment records under this order number)

    2. Sufficient payment within validity period:

      • Order status change notification: PAY_SUCCESS, received amount is doneAmountOnChain.
      • Fund arrival notification: bizStatus = TRANSFERRED_ADDRESS_IN_TERM, received amount is transferAmount. (Need to accumulate all payment records)

    3. Overpayment within validity period: Same as sufficient payment scenario.

    4. Order expires without payment:

      • Order status change notification: PAY_CLOSE, received amount is doneAmountOnChain.

    5. Payment after expiration:

      • Order status change notification: PAY_CLOSE, received amount is doneAmountOnChain.
      • Fund arrival notification: bizStatus = TRANSFERRED_ADDRESS_DELAY, received amount is transferAmount. (Need to accumulate all payment records)

    In summary, except for cases of insufficient payment within validity period, you only need to focus on the bizStatus and doneAmountOnChain fields in order status change notifications to confirm the received funds.

    # 6. Address payment API list

    # 6.1 Query the list of support chains

    • Data type: JSON (content-type: application/json)
    • Request method: GET
    • Path: /v1/pay/address/chains
    • Verification method: Merchant signature verification

    Interface Description:

    Query all available chains that support payment with the provided currency

    Parameter Description

    Request parameters:

    Field Name Type Required Description
    currency string Yes The currency to create the order in.

    Response parameters:

    Field Name Type Description
    currency string The currency to be paid
    chains []*ChainNameItem The list of Gate chains where the payment can be made for the specified currency

    ChainNameItem

    Field Name Type Description
    chain string The Gate chain
    currency string The currency to be paid
    full_curr_type string The symbol of the currency including the network information, an important parameter for placing orders
    symbol string The trading symbol on the blockchain
    explorer_url string The explorer link, explorer + token_address

    查询支持链列表，请求示例

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/chains?currency=BTC' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1673311329984' \
--header 'X-GatePay-Nonce: 7248468283' \
--header 'X-GatePay-Signature: a4581433e3f9ef4cf3e9f91bd5fb5943ca25488815e412146b4c2bed96d285cc69b4599950e2e4f894b3a205f2e17e28e252bfa635e0a7a80a1fcbb8a7b94b0d' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--data-raw ''

    Example of request for querying chains that support the payment currency

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "currency": "BTC",
      "chains": [
         {
            "chain": "BTC",
            "currency": "BTC",
            "full_curr_type": "BTC",
            "symbol": "BTC",
            "explorer_url": ""
         },
         {
            "chain": "HT",
            "currency": "BTC",
            "full_curr_type": "BTC_HT",
            "symbol": "BTC_HT",
            "explorer_url": ""
         },
         {
            "chain": "BSC",
            "currency": "BTC",
            "full_curr_type": "BTC_BSC",
            "symbol": "BTC_BSC",
            "explorer_url": ""
         }
      ]
   }
}

    # 6.2 Query the list of supported currencies

    • Data type：JSON （content-type：application/json）
    • Request method：GET
    • Path: /v1/pay/address/currencies
    • Verification method：Merchant signature verification

    Interface Description:

    Query the list of all currencies supported for Gate address payment

    Parameter Description:

    Request parameters:

    No request parameters required

    Response parameters:

    Field Name Type Description
    currencies []string List of available currencies for payment.

    Examples of request for querying the list of all currencies supported for Gate address payment

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/currencies' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673323157257' \
--header 'X-GatePay-Nonce: 8965308574' \
--header 'X-GatePay-Signature: 21386c0603a7bb7d2b70f47e908fa863c4b7e6ce63c565ef85a44f3053f6a3c04177423c9889b550d015f9c4e4a225c92c3c0da6f063ae0992dff150bb18fb1e' \
--data-raw ''

    Response to request for querying the list of all currencies supported for Gate address payment

    {
   "code": "000000",
   "data": {
      "currencies": [
         "USD",
         "USDT",
         "BTC",
         "ETH",
         "EOS",
         "LTC",
         "BCH",
         "XRP",
         "ZEC",
         "ADA",
         "GT",
         "BNB",
         "DOGE",
         "DOT",
         "SHIB",
         "UNI",
         "FIL",
         "STEPG",
         "SUPE",
         "LION",
         "FROG",
         "WMHH"
      ]
   },
   "errorMessage": "",
   "status": "SUCCESS"
}

    # 6.3 Query the supported payment currencies for convert payment order

    • Data type：JSON （content-type：application/json）
    • Request method：GET
    • Path: /v1/pay/address/supportedconvertcurrencies
    • Verification method: Merchant signature verification

    Interface Description:

    Users can query the supported payment currency for the converted payment order, and then selects one to create an convert payment order

    Parameter Description:

    Request parameters:

    Field Name Type Required Description
    currency string Yes Currency of the order.

    Response parameters:

    Field Name Type Description
    currencies []string List of currencies that support convert to the order currency

    Example of request for querying the list of supported payment currency for the convert payment order

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/supportedconvertcurrencies?currency=BTC' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw ''

    A response to request to query the list of supported payment currency for convert payment order

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "currencies": [
            "BTC",
            "USD",
            "USDT",
            "ETH",
            "XRP",
            "ZEC",
            "GT",
            "BNB",
            "DOT",
            "SHIB",
            "LION"
        ]
    }
}

    # 6.4 Place Order

    • Data type：JSON （content-type：application/json）
    • Request method：POST
    • Path: /v1/pay/address/create
    • Verification method: Merchant signature verification

    Interface Description:

    Create an order. When the order currency and payment currency are consistent, create a direct address payment order; if the order currency and payment currency are inconsistent, create a convert address payment order.

    Parameter Description:

    Request parameters:

    Field Name Type Required Description
    merchantTradeNo string Yes Merchant transaction ID in the merchant's system.
    currency string Yes Order currency.
    orderAmount string Yes Order amount.
    payCurrency string No User-selected payment currency, not required for non-flash payment orders.
    env EnvRequest Yes Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS.
    goods GoodsRequest Yes Goods.
    orderExpireTime int64 Yes Merchant-specified expiration time of the order, in milliseconds.
    returnUrl string No Callback URL for payment completion.
    cancelUrl string No Callback URL for payment cancellation.
    merchantUserId int64 Yes Unique consumer ID from the merchant’s platform.
    chain string Yes Selected chain name.
    fullCurrType string Yes Currency field that includes the chain name and corresponds to the specific currency on the specific chain.
    channelId string Yes Client Name.

    EnvRequest

    Field Name Type Required Description
    terminalType string Yes The terminal type used to create the order.

    GoodsRequest

    Field Name Type Required Description
    goodsName string No Name of the goods
    goodsDetail string No Details of the goods

    Response parameters:

    Field Name Type Description
    prepayId string ID of the created payment order
    terminalType string Terminal type of the created order
    expireTime string Expiration time of the payment order in milliseconds
    chain Chain The chain and address bound to the payment order for address payment

    Chain

    Field Name Type Description
    chain_type string Name of the chain
    address string Receiving address of the chain binding to the order

    # 6.4.1 Place a non-convert address payment order

    Place a non-convert address payment order, request example

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673323831902' \
--header 'X-GatePay-Nonce: 6225572445' \
--header 'X-GatePay-Signature: 8be2d2efcd59354067cfcde2a38ce5921a0ccf39855331971d0855f79fc7e5218782319e0615559a38c9a95b9e9cd6d6de4b3f4e04a8f81458542c369cef5f10' \
--data-raw '{
"merchantTradeNo": "93840202212210025",
"currency": "BTC",
"orderAmount": "2.1",
"env": {
"terminalType": "MINIAPP"
},
"goods": {
"goodsName": "USDT_PAY_BTC_TEST",
"goodsDetail": "yc"
},
"orderExpireTime": 1673410179000,
"returnUrl": "www.test1.com",
"cancelUrl": "www.test2.com",
"merchantUserId": 1336974,
"chain": "BSC",
"fullCurrType": "BTC_BSC",
"channelId": "123456"
}'

    Response to request to place a non-convert address payment order

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "prepayId": "47656656276819968",
      "terminalType": "MINIAPP",
      "expireTime": 1673410179000,
      "chain": {
         "chain_type": "BSC",
         "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD"
      }
   }
}

    # 6.4.2 Convert payment order

    Note：Considering exchange rate fluctuations, the maximum payment time of the convert payment order shall not exceed 10 minutes

    Example of request to place a convert payment order.

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/create' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673328735311' \
--header 'X-GatePay-Nonce: 6685832510' \
--header 'X-GatePay-Signature: cbaa0ea384fd5381c418987007136bb70ea88d962927a69f644cd0c2dc54daa605eb44b67eeb2c92eff989fa02d04f0559543bed125a403474c3b09896bfd050' \
--data-raw '{
"merchantTradeNo": "93840202212210017",
"currency": "BTC",
"orderAmount": "2.1",
"payCurrency": "USDT",
"env": {
"terminalType": "MINIAPP"
},
"goods": {
"goodsName": "USDT_PAY_BTC_TEST",
"goodsDetail": "yc"
},
"orderExpireTime": 1673415121000,
"returnUrl": "www.test1.com",
"cancelUrl": "www.test2.com",
"merchantUserId": 1336974,
"chain": "BSC",
"fullCurrType": "BTC_BSC",
"channelId": "123456"
}'

    Response to request to place a convert payment order.

    {
   "status": "SUCCESS",
   "code": "000000",
   "errorMessage": "",
   "data": {
      "prepayId": "47677222950014976",
      "terminalType": "MINIAPP",
      "expireTime": 1673329335572,
      "chain": {
         "chain_type": "BSC",
         "address": "0x68C1EC61df04B4e8CCcc94687071bEeA0cac738b"
      }
   }
}

    # 6.5 Query payment order details

    • Data type：JSON （content-type：application/json）
    • Request method：GET
    • Path: /v1/pay/address/query
    • Verification method: Merchant signature verification

    Interface Description:

    Check the details of the new address payment order, the specified parameters must correspond to the address payment order, otherwise an error message will be returned.

    Parameter description:

    Request parameters:

    Field Name Type Required Description
    prepayId string Yes Prepay order ID for address payment
    merchantTradeNo string Yes Merchant system transaction number

    Response parameters:

    Field Name Type Description
    prepayId string Payment order ID
    merchantId int64 Gate UID used to apply for a merchant account
    merchantTradeNo string Merchant system transaction number
    transactionId string Transaction ID
    goodsName string Product name provided by the merchant when creating the order
    currency string Currency of the order
    orderAmount string Amount of the order
    payCurrency string Currency that the user actually paid, which is the same as the order currency in non-flash payment orders
    payAmount string Amount that the user should pay
    rate string Exchange rate between the order currency and the user's payment currency, for example, 1 BTC for 20,000 USDT
    status string Order status, PENDING for processing, PROCESS for payment enough but not yet confirmed on the blockchain within the order validity period, PAID for payment success, EXPIRED for order expired
    createTime int64 Order creation time
    expireTime int64 Order expiration time
    transactTime int64 Time when the order was traded within Gate
    order_name string Order name
    transaction_info ChainTransactionInfo Overview of the order's transaction on the blockchain
    channelId string Client Name
    chain string Network name
    address string Collection address

    ChainTransactionInfo

    Field Name Type Description
    done_amount string The amount confirmed on-chain during the order's validity period.
    confirming_list []*ConfirmItem List of payments in progress during the order's validity period.

    ConfirmItem

    Field Name Type Description
    amount string Payment amount in the payment record
    confirm int Number of confirmations

    Example of request to query payment orders

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/query?prepayId=1661239048576446&merchantTradeNo=43959345943769874395' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw ''

    Response to request to query payment order

    {
   "prepayId": "1661239048576446",
   "merchantId": 10002,
   "merchantTradeNo": "43959345943769874395",
   "transactionId": "347827943294834379",
   "goodsName": "abc",
   "currency": "BTC",
   "orderAmount": "9.88",
   "payCurrency": "USDT",
   "payAmount": "197600",
   "rate": "20000",
   "status": "PENDING",
   "createTime": 1663657128148,
   "expireTime": 1664089128000,
   "transactTime": 1663829928000,
   "order_name": "orderName",
   "channelId": "123456",
   "transaction_info": {
      "done_amount": "8.88",
      "confirming_list": [
         {
            "amount": "0.35",
            "confirm": 3
         },
         {
            "amount": "0.65",
            "confirm": 4
         }
      ]
   }
}

    # 6.6 Refund

    Note：Refund can only be made to the payment account of the Gate user, so the Gate Uid of the user who receives the refund is required.

    # 6.6.1 Non-convert payment order refund

    • Data type：JSON （content-type：application/json）
    • Request method：POST
    • Path: /v1/pay/address/refund
    • Verification method: Merchant signature verification

    Interface Description:

    Initiate a refund for the direct address payment order, which is only applicable to the direct address payment order. If the provided parameters correspond to the converted payment order, an error message will be returned.

    Parameter description:

    Request parameters:

    Field Name Type Required Description
    refundRequestId string Yes The merchant's refund request ID
    prepayId string Yes The ID of the corresponding payment order
    refundAmount string Yes The amount to be refunded
    refundReason string No The reason for the refund
    receiverId string Yes The Gate user ID of the recipient of the refund for address payment

    Response Type:

    Field Name Type Description
    refundRequestId string Merchant's refund request id
    prepayId string The id of the payment order to be refunded
    orderAmount string The amount of the original payment order
    refundAmount string The amount to be refunded

    Example of request for refund of non-convert payment order

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--data-raw '{
    "refundRequestId": "483902480932841787",
    "prepayId": "1665553233227833",
    "refundAmount": "20",
    "refundReason": "test refund function",
    "receiverId": 598816
}'

    Response to request for refund of non-convert payment order

    {
    "refundRequestId": "483902480932841787", 
    "prepayId": "1665553233227833", 
    "orderAmount": "14.9", 
    "refundAmount": "4.9" 
}

    # 6.6.2 Convert payment order refund

    • Data type：JSON （content-type：application/json）
    • Request method：POST
    • Path: /v1/pay/address/refundconvert
    • Verification method: Merchant signature verification

    Interface Description

    Initiate a refund for the convert address payment order, which is only applicable to the convert address payment order. If the provided parameters correspond to the direct payment order, an error message will be returned.

    Parameter Description:

    Request Parameters:

    Field Name Type Required Description
    refundRequestId string Yes Merchant request refund number
    prepayId string Yes Payment order ID for refund
    refundOrderCurrency string Yes Refund order currency
    refundOrderAmount string No Refund order amount in the corresponding currency
    refundPayCurrency string Yes Refund payment currency
    refundPayAmount string Yes Refund payment amount in the corresponding currency
    refundReason string Yes Reason for refund
    receiverId string Yes Gate system user ID for refund recipient in address payment

    Response Type:

    Field Name Type Required Description
    refundRequestId string Yes Merchant's refund request ID
    prepayId string Yes ID of the corresponding payment order
    orderCurrency string No Currency of the order
    orderAmount string No Amount of the order
    refundOrderAmount string No Refund amount in the currency of the order
    payCurrency string No Currency used by the user for payment
    payAmount string No Amount the user should have paid for the order
    refundPayAmount string No Refund amount in the currency used by the user for payment

    Example of request for refund of convert payment order

    curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/address/refundconvert' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1673328925473' \
--header 'X-GatePay-Nonce: 3709309048' \
--header 'X-GatePay-Signature: 69dcbb7b487f5302032371fb3b0ec7505ae50b18666240099f86485c48b9f64d0b07cc3466da592ab6d1ff27c1ae08bfb7212fe6f051b24f381b1a9fa5f40e20' \
--data-raw '{
    "refundRequestId": "483902480932841787",
    "prepayId": "1665553233227833",
    "refundOrderCurrency": "BTC",
    "refundOrderAmount": "1.1",
    "refundPayCurrency": "USDT",
    "refundPayAmount": "1000.1",
    "refundReason": "refund test",
    "receiverId": 123456
}'

    Response to request for refund of convert payment order

    {
   "status": "SUCCESS",
   "code": "00000",
   "errorMessage": "",
   "data": {
      "refundRequestId": "483902480932841787",
      "prepayId": "1665553233227833", 
      "orderCurrency": "BTC", 
      "orderAmount": "2.2", 
      "refundOrderAmount": "1.1", 
      "payCurrency": "USDT", 
      "payAmount": "44000", 
      "refundPayAmount": "1000.1" 
   }
}

    # 6.7 transaction details on chain

    • Data type：JSON （content-type：application/json）
    • Request method：GET
    • Path: /v1/pay/address/transactiondetail
    • Verification method: Merchant signature verification`

    Interface Description:

    Query the transaction details of the address direct payment order on the chain, including the direct payment record within the validity period and the payment record beyond the validity period.

    Parameter Description:

    Request parameters:

    Field Name Type Required Description
    prepayId string Yes The ID of the Address Payment prepayment order

    Response parameters:

    Field Name Type Description
    prepayId string Payment ID
    merchantId int64 Gate UID used to apply for a merchant account
    merchantTradeNo string Merchant system transaction number
    transactionId string Transaction ID
    goodsName string Name of the goods
    currency string Order currency
    orderAmount string Order amount
    payCurrency string User payment currency
    payAmount string Payment amount for the order
    status string Order status
    utcCreateTime string UTC expression of order creation time
    utcExpireTime string UTC expression of order expiration time
    utcUpdateTime string UTC expression of order status update time
    transactTime int64 UTC millisecond timestamp of transaction completion in the background
    order_name string Order name
    transactionDetail *TransactionDetail Details of the on-chain transaction
    channelId string Client Name

    TransactionDetail

    Field Name Type Description
    inTerm *TxDetail Payment details within the validity period
    outOfTerm *TxDetail Payment details outside the validity period

    TxDetail

    Field Name Type Description
    done *TxDetailStateItem Transaction details confirmed on-chain
    wait *TxDetailStateItem Transaction details being confirmed on-chain

    TxDetailStateItem

    Field Name Type Description
    amount string Total amount confirmed on chain
    txList []*TxItem List of payment records

    TxItem

    Field Name Type Description
    chain string Name of the blockchain.
    address string The address.
    fullCurrType string The name of the chain including network information.
    amount string The payment amount.
    txId string The transaction ID on the blockchain.
    utcCreateTime string The UTC timestamp when the payment record was detected on the blockchain, for example, 2023-01-07 14:04:02.
    utcUpdateTime string The UTC timestamp when the payment record status was updated on the blockchain, for example, 2023-01-07 14:04:02.

    Example of a request to query transaction details on the chain

    curl --location --request GET 'https://openplatform.gateapi.io/v1/pay/address/transactiondetail?prepayId=40100646616043520' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: ygMRT5SdrGpiISVV' \
--header 'X-GatePay-Timestamp: 1671522977660' \
--header 'X-GatePay-Nonce: 9170105160' \
--header 'X-GatePay-Signature: b76949cf84c8ee9b11af0526adaf8aca72e8f777b35777452b00b920624b7ec4e9ef7d62b80109f61cdb7caaa78d00af02cd270f1c01d84f81aa1ee28659afb1' \
--data-raw ''

    Response to request for querying on-chain transaction details

    {
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "40100646616043520", 
        "merchantId": 10002, 
        "merchantTradeNo": "9384029384092499", 
        "transactionId": "1671522905110477", 
        "goodsName": "",
        "currency": "BTC",
        "orderAmount": "212.999", 
        "payCurrency": "BTC", 
        "payAmount": "212.999", 
        "status": "EXPIRED", 
        "utcCreateTime": "2022-12-20 07:45:39", 
        "utcExpireTime": "2022-12-20 07:55:00", 
        "transactTime": 1671522905110,
        "order_name": "MiniApp-Payment-1#9384029384092499", ,
        "channelId": "123456"
        "transactionDetail": { 
            "inTerm": { 
                "done": { 
                    "amount": "100", 
                    "txList": [ 
                        {
                            "chain": "BTC", 
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", 
                            "fullCurrType": "BTC", 
                            "amount": "100", 
                            "txId": "dosajdajdiojawojdoiwajdojaefhs", 
                            "utcUpdateTime": "2022-12-19 11:50:00" 
                        }
                    ]
                },
                "wait": { 
                    "amount": "99",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "99",
                            "txId": "dosajdajdiojawojdoiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:50:00"
                        }
                    ]
                }
            },
            "outOfTerm": { 
                "done": {
                    "amount": "98",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "98",
                            "txId": "dosajdajdoakawojdoiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        }
                    ]
                },
                "wait": { 
                    "amount": "193",
                    "txList": [
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "97",
                            "txId": "dosajdajdiojawolakiwajdojaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        },
                        {
                            "chain": "BTC",
                            "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn",
                            "fullCurrType": "BTC",
                            "amount": "96",
                            "txId": "dosajdajdiojawolakiwajdppaikjs",
                            "utcUpdateTime": "2022-12-19 11:56:00"
                        }
                    ]
                }
            }
        }
    }
}

    # 7. Error Code

    Error Code Description Solution
    400007 Unsupported Media Type Check the supported media type for the API
    400004 Missing api_key in request parameters Use X-GatePay-Certificate-SN header to provide api_key
    400003 Invalid timestamp Check X-GatePay-Timestamp timestamp is not earlier than the current time or more than 10 seconds from the request time
    400020 Missing nonce parameter Use x-GatePay-Nonce header to provide the random string used in generating the signature
    400002 Invalid signature Check the signature algorithm
    400000 Bad Request Format Check the request data format
    400001 Invalid Request Parameters Check the request parameters
    400621 Invalid Order Amount Check the order amount parameter
    400003 Invalid Timestamp Check if the expiration time when creating an order is earlier than the current time
    400201 Payment already exists for the merchantTradeNo Check if the request to create an order is duplicate
    400000 Unknown Error Internal system error
    400620 Duplicate refund request Check if the request to create a refund is duplicate
    400604 The address payment order has not entered the final state, expired or completed Wait for the order to finish before requesting a refund
    400608 Refund amount is abnormal, less than or equal to 0 or greater than the payment order amount Check the refund amount
    400607 The refund limit for a payment order has been exceeded Only one refund is supported for a payment order
    500008 Merchant not found Confirm that the X-GatePay-Certificate-SN carries the api_key issued when the merchant registered
    500200 No available address for creating the order No available address for creating the order
    500202 Using the regular payment refund interface to refund an address payment order Use the address payment refund interface instead
    500203 Querying on-chain address payment details, but the specified order is not an address payment order Check the order ID and provide the correct address payment order ID
    500204 Address payment order refund, the specified receiving refund Gate user ID does not exist or has been banned Provide the correct Gate user UID
    500205 Refunding an address payment order for flashing currencies, but the refund currency does not match the order currency and user payment currency Check the refund parameters and ensure they match the order currency
    500206 The requested refund amount exceeds the upper limit of the refundable amount Check the parameters and correct the amount
    500207 Using the address payment refund interface to refund a non-address payment order Check the parameters and provide the address payment order ID
    500208 Using the flashing currency address payment refund interface to refund a non-flashing currency address payment order Check the parameters and provide the correct flashing currency address payment order ID
    Last Updated: 6/3/2025, 1:43:31 AM