1. Introduction to Cashier Functionality

GatePay provides merchants with a dedicated checkout page, eliminating the need to develop a front-end payment UI, and supports both QR code payments and on-chain dynamic address payments.

2. Cashier’s operating process

2.1 Flow chart

2.2 Call process

Steps 1–6: After the user selects the product, the merchant creates an order request on the merchant side and calls the checkout pre-order creation API (/v1/pay/checkout/order). Once the pre-order is successfully created, GatePay returns the order information to the merchant.

Steps 7-11: After the merchant successfully creates an order, the page will jump to the cashier according to the address described in the location field (the address is the one specified in the location field of the returned message after a prepaid order is prepaid). GatePay will verify the legitimacy of the redirected order, and if the verification is successful, it will return the order details, and pull up the register.

Steps 12-14: At the register, the user can choose to pay by scanning the code or by transferring funds to the recipient’s address. After the payment is completed and confirmed by GatePay, the order status will be asynchronously notified to the merchant's backend.

3.Steps for merchants to access the cashier

3.1 Gate Pay’s preparation for accessing

Please refer to the Gate Pay Access Preparation

3.2 Get chain information for address payment

To call the cashier order placing interface (/v1/pay/checkout/order), merchants need to provide the chain and chain network information. The process is as follows.

1. Use the interface(/v1/pay/address/currencies) to query the list of supported currencies for the address payment.
2. Then use the interface(/v1/pay/address/chains) to acquire the currency’s chain network information.

3.3 Merchant calls up Gate Pay cashier

After the merchant's backend service places an order successfully via the cashier’s order interface(/v1/pay/checkout/order), the page will jump to the cashier services according to the address specified in the location field returned by the order placing interface.

Below is the format of cashier-jumping address:

https://www.gate.com/cashier?prepayid=65466648727916544

3.4 Merchant backend obtains order information

After the user completes the payment, Gate Pay will asynchronously notify the order status to the merchant. For detailed information about asynchronous status notification of paid orders, please refer to Gate Pay Access Preparation

3.5 Cashier’s related API list

3.5.1 Place an order at the cashier

• Data type：JSON （content-type： application/json）
• Method of request：POST
• Path: /v1/pay/checkout/order
• Verification method: signature verification
• Content of request body:

Field Name	Type	Required	Description
merchantTradeNo	string	Yes	Merchant order number
currency	string	Yes	Order currency in uppercase form, such as USDT, BTC, etc.
orderAmount	string	Yes	Order amount, with a maximum precision of 6 digits
payCurrency	string	No	Payment currency for address payment. If not passed, it is the same as currency.
env	Env type	Yes	Transaction source
goods	goods type	Yes	Description of the goods
orderExpireTime	int64	No	Order expiration time in milliseconds. When not set, the default is 1 hour, and the maximum expiration time is 1 hour.
returnUrl	string	No	Return jump address after the order payment is successful, with a maximum length of 256 characters.
cancelUrl	string	No	Return jump address after the order payment fails, with a maximum length of 256 characters.
merchantUserId	int64	Yes	Unique consumer ID from the merchant’s platform.
chain	string	Yes	Selected chain name.
fullCurrType	string	Yes	Currency field containing the chain name, corresponding to the specific currency on the specific chain.
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	Goods name, maximum length of 160 characters
goodsDetail	string	No	Goods description, maximum length of 256 characters
goodsType	string	No	Goods category

Example of request:

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/order' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: mZ96D37oKk-HrWJc' \
--header 'X-GatePay-Timestamp: 1695611256106' \
--header 'X-GatePay-Nonce: 1260554069' \
--header 'X-GatePay-Signature: bae293c2575ccea15592fe4cec2efa2629ea37c04fc8d856060ce76dc3cebdea9382a1088c43e14a33301a320b4a2aefc029b399c337459581220bcdc17de526' \
--data '{
    "merchantTradeNo": "163",
    "env": {
        "terminalType": "APP"
    },
    "currency": "USDT",
    "orderAmount": "118.75",
    "merchantUserId": 123,
    "goods": {
        "goodsType": "02",
        "goodsName": "Sipariş Ödemesi - 177",
        "goodsDetail": "Sipariş No : 160"
    },
    "returnUrl": "https://lotkeys.com/tr/gate-payment-response",
    "cancelUrl": "https://lotkeys.com/tr/gate-payment-response",
    "chain": "MATIC",
    "fullCurrType": "USDT_MATIC",
    "channelId": "123456"
}'

Response：

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "65466648727916544",
        "terminalType": "APP",
        "expireTime": 1677573665219,
        "qrContent": "http://openplatform.gate.io/qr/GA0cskPehKxQpshvm3Goeve8dHpwCl6yCHLSWUYrLqo=",
        "location": "https://www.gate.com/cashier?prepayid=65466648727916544",
        "payCurrency": "USDT",
        "payAmount": "1",
        "chain": {
            "chain_type": "BSC",
            "address": "0x86608d3C9f979b98a3b2417216eD859d313E339D",
            "fullCurrType": "USDT_EOS"
        },
        "channelId": "123456",
        "goodsName": "charge",
        "inUsdt": "93.99"
    }
}

Response ：

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	Description
prepayId	string	Pre-order ID created successfully
terminalType	string	Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS
expireTime	int64	Order expiration time, UTC timestamp in milliseconds. When not set, the default is 1 hour, and the maximum expiration time is 1 hour.
qrContent	string	The API returns the URL for the order QR code, developers need to generate the QR code image themselves using this content.
location	string	Redirect address for launching the cashier after placing an order successfully
payCurrency	string	Payment currency for address payment
payAmount	string	Amount to be paid for address payment
chain	chain type	Address payment chain information structure
chain_type	string	Chain name
address	string	Receiving address bound to the order on the chain
fullCurrType	string	Currency field containing the chain name, corresponding to the specific currency on the specific chain
channelId	string	Client Name
goodsName	string	Goods name when creating the order.
inUsdt	string	The corresponding USDT amount

3.5.2 Cashier’s refund interface

This is the old version of the refund interface. We recommend using the new version 3.5.3 /v2/standard/order/refund

• Data type：JSON （content-type： application/json）

• Method of request：POST

• Path: /v1/pay/checkout/refund

• Verification method: signature verification

• Request body’s content:

Field Name	Type	Required	Description
refundRequestId	string	Yes	Merchant refund ID, a unique ID generated by the merchant with a maximum length of 32 bytes
prepayId	string	Yes	Order ID, only orders that have completed payment can initiate a refund
refundOrderCurrency	string	Yes	Order currency
refundOrderAmount	string	Yes	Merchant refund amount.
refundPayCurrency	string	Yes	Refund amount currency
refundPayAmount	string	Yes	No Conver scenario.
refundReason	string	Yes	Reason for the refund
receiverId	int64	Yes	User ID of the recipient for the address payment refund in the gate system.

Example of request：

curl --location 'https://openplatform.gateapi.io/v1/pay/checkout/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1697517106839' \
--header 'X-GatePay-Nonce: 3867712705' \
--header 'X-GatePay-Signature: 9f0532870be67e51ccf5adb3f7ce4532d7b0ec692b53ed94654f8b5c6fb257d8c1e60d1d074ea783c7f10ea2dc479e43b4989ff8efaed22aec5c67e797424b93' \
--data '{
    "refundRequestId": "100036668891329",
    "prepayId": "93752669101887488",
    "refundOrderCurrency": "USDT",
    "refundOrderAmount": "100",
    "refundPayCurrency": "USDT",
    "refundPayAmount": "50",
    "refundReason": "test refund",
    "receiverId": 6790011
}'

Response：

{
    "status": "SUCCESS",
    "code": "00000",
    "errorMessage": "",
    "data": {
        "refundRequestId": "32111114322523534534",
        "prepayId": "50620368071692288",
        "orderCurrency": "BTC",
        "orderAmount": "2",
        "refundOrderAmount": "1",
        "payCurrency": "BTC",
        "payAmount": "2",
        "refundPayAmount": "0"
    }
}

Response fields:

Field Name	Type	Description
refundRequestId	string	Merchant refund request ID
prepayId	string	ID of the order to be refunded
orderCurrency	string	Order currency
orderAmount	string	Order amount
refundOrderAmount	string	The amount received by user(no fee, same as the merchant refund amount).
payCurrency	string	Payment currency
payAmount	string	No Conver scenario.
refundPayAmount	string	No Conver scenario.

3.5.3 Cashier’s refund interface V2

• Data type：JSON （content-type： application/json）

• Method of request：POST

• Path: /v2/standard/order/refund

• Verification method: signature verification

• Request body’s content:

Field Name	Type	Required	Description
refundRequestId	string	Yes	Merchant refund ID, a unique ID generated by the merchant with a maximum length of 32 bytes
prepayId	string	Yes	Order ID, only orders that have completed payment can initiate a refund
refundAmount	string	Yes	Merchant refund amount
refundReason	string	Yes	Reason for the refund
refundStyle	int64	NO	Refund methods: 1.Refund to the original payment method; 2. Refund to a specified payment method.
refundPayChannel	int64	NO	Refund payment methods: 1. Gate 2. Web3
refundToGateUid	string	NO	Refund to user ID (required if it's a Gate account).
refundChain	string	NO	Refund chain code (required if using Web3)
refundBearType	string	NO	Refund bear type 1: Merchant; 2: User
memo	string	NO	Refund memo
refundAmountTypeFull	string	NO	Refund Amount Type: 1: Full Refund; 2: Partial Refund
needNotify	boolean	NO	Is notification required
refundLimit	boolean	NO	Refund times limit
refundCurrency	string	NO	Refund currency
refundFundStatementId	int64	NO	Transaction Id for refund
refundSource	int64	NO	The source of the refund: 0: Order; 1: Transaction

• Response fields:

Field Name	Type	Description
refundRequestId	string	Merchant refund ID
prepayId	string	Order ID
refundGateId	string	Gatepay refund Id
orderAmount	string	Order amount
refundAmount	string	Refund amount
errMsg	string	Error message
orderCurrency	string	Order currency
payCurrency	string	Refund currency
payAmount	string	Merchant pay amount

Example of request：

curl --location 'https://openplatform.gateapi.io//v2/standard/order/refund' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: yq6cRqhwY6TtXRrw' \
--header 'X-GatePay-Timestamp: 1697517106839' \
--header 'X-GatePay-Nonce: 3867712705' \
--header 'X-GatePay-Signature: 9f0532870be67e51ccf5adb3f7ce4532d7b0ec692b53ed94654f8b5c6fb257d8c1e60d1d074ea783c7f10ea2dc479e43b4989ff8efaed22aec5c67e797424b93' \
--data '{
    "prepayId": "35214673103159414",
    "refundRequestId": "202508271923022",
    "refundStyle": 2,
    "refundToGateUid":10002,
    "refundAmount": "0.018",
    "currency": "USDT",
    "refundPayChannel": 1,
    "refundReason":"bourne-test",
    "refundBearType":1
}'

Response：

{
    "code": "000000",
    "data": {
        "refundRequestId": "202508271923022",
        "refundGateId": "1991045981847818240",
        "prepayId": "35214673103159414",
        "orderAmount": "10",
        "refundAmount": "0.018",
        "errMsg": "",
        "orderCurrency": "USDT",
        "payCurrency": "USDT",
        "payAmount": "0.018"
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

3.5.4 checkout order details interface

• Data type：JSON （content-type：application/json）

• Method of request：GET

• Path: /v2/pay/order/query

• Verification method: signature verification

• Request body’s content:

Field Name	Type	Required	Description
prepayId	string	No	Prepay order ID. Either prepayId or merchantTradeNo must be provided.
merchantTradeNo	string	No	Merchant order ID. Either prepayId or merchantTradeNo must be provided.

• Response fields:

Field Name	Type	Description	说明
prepayId	string	Prepay order ID
merchantId	int64	Gate UID used to apply for a merchant account
merchantTradeNo	string	Merchant trade number
transactionId	string	Transaction ID
goodsName	string	GoodsName when creating the order
currency	string	Order currency
orderAmount	string	Order amount
status	string	Order Status
createTime	int64	Order creation time in milliseconds
expireTime	int64	Expiration time of the payment order in milliseconds
transactTime	int64	Payment completion time in milliseconds
order_name	string	Order name
pay_currency	string	Currency paid by the user
pay_amount	string	Amount paid by the user
expectCurrency	string	The revenue currency specified by the merchant when creating the order. Only returned in details of orders with a specified settlement currency.
actualCurrency	string	The currency actually settled to the merchant's account by the Gate backend after the order is paid; returned in the order details only once the order has been settled.
actualAmount	string	The amount of currency actually settled to the merchant's account by the Gate backend after the order is paid; returned in the order details only once the order has been settled.
rate	string	Exchange rate for Convert payment
channelId	string	Client Name
address	string	Collection address
appLogo	string	Application Logo
appName	string	Application name
chain	string	Network name
channel_type	string	Channel type
fromAddress	string	from address
fullCurrType	string	The name of the chain including network information
inUsdt	string	The corresponding USDT amount
location	string	The Web payment component redirect URL after creating the order
merchantName	string	Merchant name
pay_account	string	Payment account
qrcode	string	The API returns the URL for the order QR code, developers need to generate the QR code image themselves using this content
returnUrl	string	The URL to return to after a successful payment. Maximum length of 256 characters.
scheme	string	Encrypted transaction hash
showChainNameEn	string	The English name of chain
totalFee	string	Total amount of the order
txHash	string	Transaction hash
transaction_info	ChainTransactionInfo	Transaction information
whiteBrandInfo	WhiteBrandInfo	Brand information

ChainTransactionInfo :

Field Name	Type	Description
done_amount	string	Actual completed amount
confirming_list	ConfirmItem	List of payments pending confirmation within and outside the validity period

ConfirmItem :

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

WhiteBrandInfo:

Field Name	Type	Description
logoUrl	string	Brand logo url
brand	string	brand
payWays	array	Payment way list

Order status value：

Value	Description
PENDING	Order pending payment
PROCESS	Payment processing
PAID	Payment succeeded
EXPIRED	Order expired
CANCELLED	Order cancelled by merchant
ERROR	Payment failed due to error
BLOCK	Static address payment block
AUDITING	Order is under auditing
REJECTED	Order is rejected
AUDIT_ERROR	Approved but payment error

Example of request：

curl --location --request GET 'https://openplatform.gateapi.io/v2/refund/support/chains?prepayId=55607130580844563' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

Response：

{
  "code": "000000",
  "data": {
    "bizCode": "0",
    "bizData": {
      "prepayId": "55607130580844563",
      "merchantId": 1627288,
      "merchantTradeNo": "Gate-Pre-1763519042444",
      "transactionId": "",
      "goodsName": "Gate-Pre-Good-Name",
      "currency": "USDT",
      "orderAmount": "1",
      "status": "PENDING",
      "createTime": 1763519042794,
      "expireTime": 1763522642750,
      "transactTime": 0,
      "order_name": "Gate-Pre-176351904244411",
      "pay_currency": "USDT",
      "pay_amount": "1",
      "expectCurrency": "USDT",
      "actualCurrency": "",
      "actualAmount": "",
      "rate": "1",
      "channelId": "",
      "address": "0x7aD5b3E4695a85f0248d675861b44Bd968Ed22e5",
      "appLogo": "https://gimg2.staticimgs.com/image/7f4993b72edab240c4aa0be9ee5bb7f91d7b5215.png",
      "appName": "TestApp",
      "chain": "ETH",
      "channel_type": "",
      "fromAddress": "",
      "fullCurrType": "USDT_ETH",
      "inUsdt": "1",
      "location": "https://www.gate.com",
      "merchantName": "TestMerchant",
      "pay_account": "",
      "qrcode": "http://openplatform.gate.io/qr/X9HvcRyUVtqqRsizJBGHpMQ5r3IiT7OsD2dgS9cB-w8",
      "returnUrl": "https://www.gate.com",
      "scheme": "gatepay056e08b4e2e44bfe",
      "showChainNameEn": "USDT_ETH",
      "totalFee": "1",
      "transaction_info": {
        "confirming_list": [],
        "done_amount": "0"
      },
      "txHash": "",
      "whiteBrandInfo": {
        "brand": "anlitesttr",
        "logoUrl": "https://gimg2.staticimgs.com/image/1627288/edecb5338bd4b6aca36d9dcbb5d17907c5226e66911b88f6c0e232e948516880.png",
        "payWays": [
          "web3",
          "gate"
        ]
      }
    },
    "bizMessage": ""
  }, 
  "status": "SUCCESS",
  "errorMessage": ""
}

3.5.5 Query the supported network for currencies for refund interface

• Data type：JSON （content-type：application/json）

• Method of request：GET

• Path: /v2/refund/support/chains

• Verification method: signature verification

• Request body’s content:

Field Name	Type	Required	Description
currency	string	YES	Order Currency in uppercase, such as USDT, BTC, etc

Response fields:

Field Name	Type	Description
currency	string	The currency to create the order in
chains	[] ChainItem	The list of Gate chains where the payment can be made for the specified currency

ChainItem :

Field Name	Type	Description
chain	string	The Gate chain
currency	ChainItem	The currency to be paid
full_curr_type	string	The symbol of the currency including the network information
symbol	string	The trading symbol on the blockchain
explorer_url	string	The explorer link, explorer + token_address
show_chain_name_en	string	The English name of chain
hasWithdrawMemo	int	Has a withdrawal note, 0: no, 1: yes
withdrawPercent	string	Withdrawal fee percentage
withdrawFix	string	Fixed withdrawal fee

Example of request:

curl --location --request GET 'https://openplatform.gateapi.io/v2/refund/support/chains?currency=USDT' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

Response:

{
  "code": "000000",
  "data": {
    "currency": "USDT",
    "chains": [
      {
        "chain": "MATIC",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "1",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "MATIC"
      },
      {
        "chain": "SOL",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "0.1",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "SOL"
      },
      {
        "chain": "ETH",
        "currency": "USDT",
        "symbol": null,
        "hasWithdrawMemo": 0,
        "withdrawPercent": "0",
        "withdrawFix": "7.4",
        "full_curr_type": "",
        "explorer_url": null,
        "show_chain_name_en": "ETH"
      }
    ]
  },
  "status": "SUCCESS",
  "errorMessage": ""
}

3.5.6 Cashier Refund Details Inquiry Interface

• Data type: JSON (content-type: application/json)

• Method of request：GET

• Path: /v2/pay/refund/details

• Verification method：signature verification

• Request body’s content:

Field Name	Type	Required	Description
refundRequestId	string	YES	erchant refund ID, a unique ID generated by the merchant with a maximum length of 32 bytes

• Response fields:

Field Name	Type	Description
refundRequestId	string	The merchant's refund request ID
gateRefundId	string	Refund Id generated byGatePay
refundId	string	The merchant's refund request ID
orderId	string	Order Id
merchantTradeNo	string	Merchant transaction number
createTime	int64	Refund creation time
transactTime	int64	Time when the refund was traded within Gate
transactionId	string	Transaction ID
txHash	string	Transaction hash for web3
orderAmount	string	Order amount
orderCurrency	string	Order currency
requestAmount	string	Requested refund amount
requestCurrency	string	Requested refund currency
amount	string	Refund amount
currency	string	Refund currency
status	string	Refund status
remark	string	Refund order remark
refund_style	string	Refund style 1: Refund to original payment method 2: Refund to specified method
refund_pay_channel	string	Refund payment methods: 1. Gate; 2. Web; 3.
refund_address	string	Refund address
refund_chain	string	Refund network
refundBearType	string	Refund bear type 1: Merchant; 2: User
refund_amount_type	string	Refund Amount Type: 1: Full Refund; 2: Partial Refund
refund_account_type	string	Refund deduction account types: 1: Payment account; 2: Spot account
refund_gas_amount	string	Refund processing fees apply only to refunds processed via Web3.
refund_fail_reason	string	Reasons for refund failure
refund_to_gate_uid	string	Refund to gate user uid
channelId	string	Client name
nickName	string	User nickname
payerId	string	Payer's user ID
fromAddress	string	From address
payChannel	string	Payment method: Web3 payment Gate Pay
billType	string	Bill type
goodsName	string	GoodsName when creating the order
totalRequestAmount	string	Order Level - Requested Refund Amount
totalRequestCurrency	string	Order Level - Requested Refund Currency
totalReceiveAmount	string	Order Level - Actual amount received
totalReceiveCurrency	string	Order Level - Actual currency received
refundDetails	[] RefundDetailItem	Refund order details list

RefundDetailItem :

Field Name	Type	Description
transactionId	string	Transaction ID
transactTime	int64	Time when the refund was traded within Gate
payChannel	string	Payment method: Web3 payment Gate Pay
status	string	Payment status
amount	string	Refund amount
currency	string	Refund Currency
chain	string	Refund network
address	ChainItem	Merchant Collection address
hash	string	Transaction hash for web3
remark	string	Remark
billType	string	Bill type

Refund status values：

Value	Description
PENDING	Pending payment
PROCESS	Payment processing
CHECK	Auditing
SUCCESS	Refund succss
FAIL	Refund failure

Example of request:

curl --location --request GET 'https://openplatform.gateapi.io/v2/pay/refund/details?refundRequestId=re8350538543' \
--header 'X-GatePay-Certificate-ClientId: SkZlbKOqPoMwnxhl' \
--header 'X-GatePay-Timestamp: 1763518379610' \
--header 'x-GatePay-Nonce: 3133420233' \
--header 'x-GatePay-Signature: 63f61245ee7fce137de2322eb98e7e416a4bea2c44653eaadc8d771c534767557511fbe9ac287d1cdaeb217c852e66c1275719cf2c61ef7a84e626979e5d6f5e' \
--header 'GatePay-client-Type: IOS' \
--header 'Cookie: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjEwMzIzNjUsImlwIjoiLzVveGpsYnNpSG1YYnRSdUgxeGVNTDVHNXN0UytmQkhsN3ljU2kyWDBmcUk1RzJXUmNMV2dybz0iLCJpcFJlc3RyaWN0IjoiQ1BZUHltWkVIOU8wcGtOdFBPd1ZibW5ocVhPenpjRXJxZ2t5RlZvPSIsImRldmljZVR5cGUiOiJBanVvdjVRVWk4Zkp3em1mTEdvSURDdUU5eDJjUzlxSUNxcGZHN3c9IiwiZGV2aWNlSWQiOiJtbHdqRWpTSEtFZHEwSXc4SkNjZWlvbk83eGIyRlg0YXFkWFJCZ0taSlYzZDd0dnk3NHpZcWlsMmNuOU9Mb1Y5bE1zMHBDemw3SG9jMEdSaVRNZ0ZrUT09IiwidWlkIjoiSXRxdlJNMHkxblN4YWZ6cW80czVndGxNejkzYlhoU1hXRnU3S01vaDdXS1FtYWR4Y3VBPSJ9.eaIOdmiFdGzXtOaWGSncI-QDp_ak5dNHx3Xa5H9iYQY' \
--header 'Content-Type: application/json' \
--data-raw ''

Response:

{
    "code": "000000",
    "data": {
        "refundRequestId": "re8350538543",
        "gateRefundId": "55600765439311884",
        "refundId": "re8350538543",
        "orderId": "55600765439311876",
        "merchantTradeNo": "55600765439311875",
        "createTime": 1763341682831,
        "transactTime": 1763341682885,
        "transactionId": "55600765439311884",
        "txHash": "",
        "orderAmount": "1",
        "orderCurrency": "USDT",
        "requestAmount": "1",
        "requestCurrency": "USDT",
        "amount": "1",
        "currency": "USDT",
        "status": "SUCCESS",
        "remark": "test refund",
        "refund_style": 2,
        "refund_pay_channel": 1,
        "refund_address": "",
        "refund_chain": "",
        "refund_bear_type": 1,
        "refund_amount_type": 0,
        "refund_account_type": 0,
        "refund_gas_amount": "0",
        "refund_fail_reason": "",
        "refund_to_gate_uid": 22178618,
        "channelId": "Test",
        "nickName": "Test",
        "payerId": 22178618,
        "fromAddress": "",
        "payChannel": "qrcode_pay",
        "billType": 2,
        "goodsName": "test",
        "totalReceiveAmount": "1",
        "totalReceiveCurrency": "USDT",
        "totalRequestAmount": "1",
        "totalRequestCurrency": "USDT",
        "refundDetails": [
          {
            "address": "0xCfbC0ac54223eC44c5a4987c447A8C460BdB9e7b",
            "amount": "1",
            "billType": 2,
            "chain": "BSC",
            "currency": "USDT",
            "hash": "",
            "payChannel": "qrcode_pay",
            "status": "SUCCESS",
            "transactTime": 1763341682866,
            "transactionId": "55600765439311884"
          }
        ]
    },
    "status": "SUCCESS",
    "errorMessage": ""
}

4. Notifications for Checkout Counter Payment

Checkout Counter Payment includes payment via Gate Pay and Web3 payment (address payment).

For notifications for payment via Gate Pay, see Common - 4.1 Asynchronous notification of order status, orderAmount indicates the paid amount for orders with a successful payment status.

For notifications for address payment, see Address Payment - 4.3 Message structure, Within the on-chain validity period, waitAmountOnChain indicates the amount pending confirmation, while doneAmountOnChain indicates the confirmed amount.

5. FAQ

Q:How long is the order valid for?

A: Merchants can set the expiration time for the order at the interface when creating prepaid orders. By default, the expiration time is one hour and the maximum expiration time can't exceed one hour.

Q:How to calculate the signature in the interface?

A:For details, please refer to the security specification chapter in the GatePay Access Preparation。

Q:What is address payment delayed payment?

A: Definition: Delayed payment refers to the payment with the broadcasting time recorded on the chain later than the expiration time or termination time of the order.

Delayed non-convert payment order: deposit the user's fund to the merchant's payment account

Delayed convert payment order: keep the user's payment funds within the Gate, and do not deposit the funds to the merchant's payment account

Q: How does the merchant's backend obtain the order payment result?

A:After the payment is successful, Gate Pay will asynchronously notify the merchant's backend of the order status. For detailed information about asynchronous notification of order status, please refer to Gate Pay Access Preparation