{ "openapi": "3.1.0", "info": { "title": "GatePay Address Payment API", "description": "GatePay Address Payment APIs for crypto payment via blockchain address.", "version": "1.0.0" }, "servers": [ { "url": "https://openplatform.gateapi.io" } ], "paths": { "/v1/pay/address/chains": { "get": { "summary": "Query Supported Chains", "description": "Query all available chains that support payment with the provided currency", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" }, { "name": "currency", "in": "query", "required": true, "description": "The currency to create the order in.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainsResponse" }, "example": { "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": "" } ] } } } } } } } }, "/v1/pay/address/currencies": { "get": { "summary": "Query Supported Currencies", "description": "Query the list of all currencies supported for Gate address payment", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrenciesResponse" }, "example": { "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" } } } } } } }, "/v1/pay/address/supportedconvertcurrencies": { "get": { "summary": "Query Convert Supported Currencies", "description": "Users can query the supported payment currency for the converted payment order, and then selects one to create an convert payment order", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" }, { "name": "currency", "in": "query", "required": true, "description": "Currency of the order.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrenciesResponse" }, "example": { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "currencies": [ "BTC", "USD", "USDT", "ETH", "XRP", "ZEC", "GT", "BNB", "DOT", "SHIB", "LION" ] } } } } } } } }, "/v1/pay/address/create": { "post": { "summary": "Place Order", "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.", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "example": { "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" } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" }, "example": { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "prepayId": "47656656276819968", "terminalType": "MINIAPP", "expireTime": 1673410179000, "chain": { "chain_type": "BSC", "fullCurrType": "USDT_BSC", "address": "0x1699dB45Dc502A0395038265fCBC4Fa05d6afFBD" } } } } } } } } }, "/v1/pay/address/query": { "get": { "summary": "Query Order", "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.", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" }, { "name": "prepayId", "in": "query", "required": false, "description": "Prepay order ID for address payment; use with merchantTradeNo as either-or, and provide at least one", "schema": { "type": "string" } }, { "name": "merchantTradeNo", "in": "query", "required": false, "description": "Merchant system transaction number; use with prepayId as either-or, and provide at least one", "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "description": "Address payment order details", "$ref": "#/components/schemas/AddressQueryOrderData" } } } ] }, "example": { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "prepayId": "1661239048576446", "merchantId": 10002, "merchantTradeNo": "43959345943769874395", "transactionId": "347827943294834379", "goodsName": "abc", "fromAddress": "", "currency": "BTC", "orderAmount": "9.88", "payCurrency": "USDT", "payAmount": "197600", "surchargeAmount": "", "fiatCurrency": "", "fiatAmount": "", "fiatRate": "", "rate": "20000", "status": "PENDING", "createTime": 1663657128148, "expireTime": 1664089128000, "transactTime": 1663829928000, "order_name": "orderName", "totalFeeAmount": "0", "totalInstitutionFeeAmount": "0", "totalSettleAmount": "", "payDetails": [ { "transactionId": "347827943294834379", "payType": "Web3Pay", "payTime": "1663829928000", "payAmount": "9.88", "payCurrency": "USDT", "feeAmount": "0", "institutionFeeAmount": "0", "settleAmount": "9.88", "settlementStatus": "done", "txId": "0xabc123def456" } ], "transaction_info": { "done_amount": "10.11", "done_amount_total": "10.11", "confirming_list": [ { "amount": "0.35", "confirm": 3 }, { "amount": "0.65", "confirm": 4 } ], "done_tx_item_list": [ { "chain": "BSC", "address": "0x5E86088F084dD253fBd6d5ad955af6f53EFC8073", "fullCurrType": "USDT_BSC", "amount": "10.11", "txId": "D1758212402891", "utcCreateTime": "2025-09-18 08:20:03", "utcUpdateTime": "2025-09-18 08:20:03", "fromAddress": "LHDwcMPVPXXvrmSlRVeEcxsLUCvtThHLa" } ], "confirming_tx_item_list": [ { "chain": "BSC", "address": "0x5E86088F084dD253fBd6d5ad955af6f53EFC8022", "fullCurrType": "USDT_BSC", "amount": "10.11", "txId": "D1758212402811", "utcCreateTime": "2025-09-18 08:20:03", "utcUpdateTime": "2025-09-18 08:20:03", "fromAddress": "LHDwcMPVPXXvrmSlRVeEcxsLUCvtThHLa" } ] }, "channelId": "123456", "chain": "ETN", "address": "0x67C30f439D7734f393c2F4a587B198b8F4086Ccb" } } } } } } } }, "/v1/pay/address/refund": { "post": { "summary": "Refund (Direct Payment)", "description": "Initiate a refund for the direct address payment order, which is only applicable to the direct address payment order.", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" }, "example": { "refundRequestId": "483902480932841787", "prepayId": "1665553233227833", "refundAmount": "20", "refundReason": "test refund function", "receiverId": 598816 } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" }, "example": { "status": "SUCCESS", "code": "000000", "errorMessage": "", "data": { "refundRequestId": "483902480932841787", "prepayId": "1665553233227833", "orderAmount": "14.9", "refundAmount": "4.9" } } } } } } } }, "/v1/pay/address/transactiondetail": { "get": { "summary": "transaction details on chain", "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.", "parameters": [ { "$ref": "#/components/parameters/X-GatePay-Certificate-ClientId" }, { "$ref": "#/components/parameters/X-GatePay-Signature" }, { "$ref": "#/components/parameters/X-GatePay-Timestamp" }, { "$ref": "#/components/parameters/X-GatePay-Nonce" }, { "name": "prepayId", "in": "query", "required": false, "description": "The ID of the Address Payment prepayment order", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetailResponse" }, "example": { "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", "utcUpdateTime": "2022-12-20 07:46:00", "transactTime": 1671522905110, "order_name": "MiniApp-Payment-1#9384029384092499", "channelId": "123456", "transactionDetail": { "inTerm": { "done": { "amount": "100", "txList": [ { "chain": "BTC", "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN", "fullCurrType": "BTC", "amount": "100", "txId": "dosajdajdiojawojdoiwajdojaefhs", "utcCreateTime": "2022-12-19 11:49:00", "utcUpdateTime": "2022-12-19 11:50:00", "utcConfirmingTime": "2022-12-19 11:51:00", "complianceStatus": "ACCEPTED", "utcDoneTime": "2022-12-19 11:52:00" } ] }, "wait": { "amount": "99", "txList": [ { "chain": "BTC", "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN", "fullCurrType": "BTC", "amount": "99", "txId": "dosajdajdiojawojdoiwajdojaikjs", "utcCreateTime": "2022-12-19 11:49:30", "utcUpdateTime": "2022-12-19 11:50:00", "utcConfirmingTime": "2022-12-19 11:51:30", "complianceStatus": "PEND" } ] } }, "outOfTerm": { "done": { "amount": "98", "txList": [ { "chain": "BTC", "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN", "fullCurrType": "BTC", "amount": "98", "txId": "dosajdajdoakawojdoiwajdojaikjs", "utcCreateTime": "2022-12-19 11:55:00", "utcUpdateTime": "2022-12-19 11:56:00", "utcConfirmingTime": "2022-12-19 11:57:00", "complianceStatus": "ACCEPTED", "utcDoneTime": "2022-12-19 11:58:00" } ] }, "wait": { "amount": "193", "txList": [ { "chain": "BTC", "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN", "fullCurrType": "BTC", "amount": "97", "txId": "dosajdajdiojawolakiwajdojaikjs", "utcCreateTime": "2022-12-19 11:55:30", "utcUpdateTime": "2022-12-19 11:56:00", "complianceStatus": "REJECTED" }, { "chain": "BTC", "address": "12eBREQqZFFDqgDfXkuBdzW2KBwhU8amPn", "fromAddress": "PAzupoupdSYaYoajDcABEUzigBRzewvzN", "fullCurrType": "BTC", "amount": "96", "txId": "dosajdajdiojawolakiwajdppaikjs", "utcCreateTime": "2022-12-19 11:55:45", "utcUpdateTime": "2022-12-19 11:56:00", "utcConfirmingTime": "2022-12-19 11:57:30", "complianceStatus": "PEND" } ] } } } } } } } } } } } }, "components": { "schemas": { "ChainsResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Request status." }, "code": { "type": "string", "description": "Response code." }, "data": { "type": "object", "properties": { "currency": { "type": "string", "description": "The currency to be paid" }, "chains": { "type": "array", "description": "The list of Gate chains where the payment can be made for the specified currency", "items": { "$ref": "#/components/schemas/ChainItem" } } } } } }, "ChainItem": { "type": "object", "properties": { "chain": { "type": "string", "description": "The Gate chain" }, "currency": { "type": "string", "description": "The currency to be paid" }, "full_curr_type": { "type": "string", "description": "The symbol of the currency including the network information, an important parameter for placing orders" }, "symbol": { "type": "string", "description": "The trading symbol on the blockchain" }, "explorer_url": { "type": "string", "description": "The explorer link, explorer + token_address" }, "show_chain_name_en": { "type": "string", "description": "The English name of chain" } } }, "CurrenciesResponse": { "type": "object", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "data": { "type": "object", "properties": { "currencies": { "type": "array", "description": "List of currencies that support convert to the order currency", "items": { "type": "string" } } } } } }, "CreateOrderRequest": { "type": "object", "description": "Request for creating a payment order.", "required": [ "merchantTradeNo", "orderExpireTime", "merchantUserId", "chain", "fullCurrType", "env", "goods", "channelId" ], "properties": { "merchantTradeNo": { "type": "string", "description": "Merchant transaction ID in the merchant's system." }, "currency": { "type": "string", "description": "Crypto currency in uppercase. Required for crypto orders together with orderAmount. Omit when creating a pure fiat order with fiatCurrency and fiatAmount (system converts to USDT). Must equal payCurrency (or payCurrency is backfilled from this)." }, "orderAmount": { "type": "string", "description": "Crypto order amount. Required together with currency for crypto orders. Omit for pure fiat orders that use fiatCurrency and fiatAmount." }, "toleranceAmount": { "type": "string", "description": "Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required." }, "fiatCurrency": { "type": "string", "description": "Fiat currency in uppercase, such as EUR, GBP, USD, CNY, JPY, AUD, CAD, CHF. For pure fiat orders, provide together with fiatAmount and omit currency/orderAmount." }, "fiatAmount": { "type": "string", "description": "Fiat order amount, with a maximum precision of 2 digits. For pure fiat orders, provide together with fiatCurrency and omit currency/orderAmount." }, "surchargeAmount": { "type": "string", "description": "Surcharge, a fee borne by the consumer." }, "payCurrency": { "type": "string", "description": "Payment currency. Optional; if omitted, it is backfilled from currency. If provided, it must equal currency." }, "env": { "$ref": "#/components/schemas/EnvRequest" }, "goods": { "$ref": "#/components/schemas/GoodsRequest" }, "orderExpireTime": { "type": "integer", "format": "int64", "description": "Merchant-specified expiration time of the order, in milliseconds." }, "returnUrl": { "type": "string", "description": "Callback URL for payment completion." }, "cancelUrl": { "type": "string", "description": "Callback URL for payment cancellation." }, "merchantUserId": { "type": "integer", "format": "int64", "description": "Unique consumer ID from the merchant’s platform." }, "chain": { "type": "string", "description": "Selected chain name." }, "fullCurrType": { "type": "string", "description": "Currency field that includes the chain name and corresponds to the specific currency on the specific chain." }, "channelId": { "type": "string", "description": "Client Name." } } }, "EnvRequest": { "type": "object", "description": "Transaction source, optional values: APP, WEB, WAP, MINIAPP, OTHERS.", "required": [ "terminalType" ], "properties": { "terminalType": { "type": "string", "description": "The terminal type used to create the order." } } }, "GoodsRequest": { "type": "object", "description": "Goods.", "properties": { "goodsName": { "type": "string", "description": "Name of the goods" }, "goodsDetail": { "type": "string", "description": "Details of the goods" } } }, "CreateOrderResponse": { "type": "object", "description": "Response parameters", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "errorMessage": { "type": "string" }, "data": { "type": "object", "properties": { "prepayId": { "type": "string", "description": "ID of the created payment order" }, "terminalType": { "type": "string", "description": "Terminal type of the created order" }, "expireTime": { "type": "string", "description": "Expiration time of the payment order in milliseconds" }, "chain": { "$ref": "#/components/schemas/Chain" } } } } }, "Chain": { "type": "object", "description": "The chain and address bound to the payment order for address payment", "properties": { "chain_type": { "type": "string", "description": "Name of the chain" }, "address": { "type": "string", "description": "Receiving address of the chain binding to the order" }, "fullCurrType": { "type": "string", "description": "The name of the chain including network information." }, "memo": { "type": "string", "description": "On-chain memo. For some chains (e.g. TON), parsed from the deposit address; may be omitted or empty when not applicable." } } }, "ApiResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Payment status" }, "code": { "type": "string", "description": "Error code" }, "errorMessage": { "type": "string", "description": "Error message" } } }, "AddressQueryOrderData": { "type": "object", "description": "Address payment order details in the response body field `data`", "properties": { "prepayId": { "type": "string", "description": "Payment order ID" }, "merchantId": { "type": "integer", "format": "int64", "description": "Gate UID used to apply for a merchant account" }, "merchantTradeNo": { "type": "string", "description": "Merchant system transaction number" }, "transactionId": { "type": "string", "description": "Transaction ID" }, "goodsName": { "type": "string", "description": "Product name provided by the merchant when creating the order" }, "currency": { "type": "string", "description": "Currency of the order" }, "orderAmount": { "type": "string", "description": "Amount of the order" }, "surchargeAmount": { "type": "string", "description": "Amount of the surcharge" }, "toleranceAmount": { "type": "string", "description": "Tolerance Amount：If the remaining unpaid amount is less than or equal to the configured tolerance amount, the order will be automatically marked as Paid, with no further payment required." }, "underpaidAmount": { "type": "string", "description": "After payment is completed, the remaining payment amount" }, "fiatCurrency": { "type": "string", "description": "Fiat order currency." }, "fiatAmount": { "type": "string", "description": "Fiat order amount." }, "fiatRate": { "type": "string", "description": "Fiat rate." }, "payCurrency": { "type": "string", "description": "Currency that the user actually paid, which is the same as the order currency in non-flash payment orders" }, "payAmount": { "type": "string", "description": "Payment amount field; interpret it together with the order mode and related amount fields" }, "rate": { "type": "string", "description": "Exchange rate between the order currency and the user's payment currency, for example, 1 BTC for 20,000 USDT" }, "status": { "type": "string", "description": "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": { "type": "integer", "format": "int64", "description": "Order creation time" }, "expireTime": { "type": "integer", "format": "int64", "description": "Order expiration time" }, "transactTime": { "type": "integer", "format": "int64", "description": "Time when the order was traded within Gate" }, "order_name": { "type": "string", "description": "Order name" }, "totalFeeAmount": { "type": "string", "description": "Cumulative fees charged. May be empty or `0` when payment flows are not settled, unpaid, or in centralized-payment-only scenarios, etc." }, "totalInstitutionFeeAmount": { "type": "string", "description": "Cumulative institution revenue share.", "example": "0" }, "totalSettleAmount": { "type": "string", "description": "Cumulative settled amount. May be empty when payment flows are not settled, etc." }, "payDetails": { "type": "array", "description": "Payment information", "items": { "$ref": "#/components/schemas/OrderQueryPayDetail" } }, "transaction_info": { "$ref": "#/components/schemas/ChainTransactionInfo" }, "channelId": { "type": "string", "description": "Client Name" }, "chain": { "type": "string", "description": "Network name" }, "address": { "type": "string", "description": "Address" }, "fromAddress": { "type": "string", "description": "Payer address" } } }, "OrderQueryPayDetail": { "type": "object", "description": "Fee and settlement information for a single payment in the flow (payDetail).", "properties": { "transactionId": { "type": "string", "description": "Payment flow / transaction ID." }, "payType": { "type": "string", "description": "Payment type: `GatePay` for Gate Pay, `Web3Pay` for Web3 payment." }, "payTime": { "type": "string", "description": "Payment time." }, "payAmount": { "type": "string", "description": "Payment amount." }, "payCurrency": { "type": "string", "description": "Payment currency" }, "feeAmount": { "type": "string", "description": "Fee amount." }, "institutionFeeAmount": { "type": "string", "description": "Institution revenue share.", "example": "0" }, "settleAmount": { "type": "string", "description": "Settled amount." }, "settlementStatus": { "type": "string", "description": "Settlement status: `pending` not settled, `done` settled." }, "txId": { "type": "string", "description": "On-chain transaction ID" } } }, "ChainTransactionInfo": { "type": "object", "properties": { "done_amount": { "type": "string", "description": "Total confirmed on-chain payment amount within the validity period" }, "done_amount_total": { "type": "string", "description": "Total confirmed on-chain payment amount within and outside the validity period" }, "confirming_list": { "type": "array", "description": "List of payments pending on-chain confirmation within the validity period", "items": { "$ref": "#/components/schemas/ConfirmItem" } }, "done_tx_item_list": { "type": "array", "description": "List of confirmed payments within and outside the validity period", "items": { "$ref": "#/components/schemas/TxItem_Query" } }, "confirming_tx_item_list": { "type": "array", "description": "List of payments pending confirmation within and outside the validity period", "items": { "$ref": "#/components/schemas/TxItem_Query" } } } }, "ConfirmItem": { "type": "object", "properties": { "amount": { "type": "string", "description": "Payment amount in the payment record" }, "confirm": { "type": "integer", "description": "Number of confirmations" } } }, "TxItem_Query": { "type": "object", "properties": { "chain": { "type": "string", "description": "Name of the blockchain." }, "address": { "type": "string", "description": "The address." }, "FromAddress": { "type": "string", "description": "from address" }, "fullCurrType": { "type": "string", "description": "The name of the chain including network information." }, "amount": { "type": "string", "description": "The payment amount." }, "txId": { "type": "string", "description": "The transaction ID on the blockchain." }, "utcCreateTime": { "type": "string", "description": "The UTC timestamp when the payment record was detected on the blockchain, for example, 2023-01-07 14:04:02." }, "utcUpdateTime": { "type": "string", "description": "The UTC timestamp when the payment record status was updated on the blockchain, for example, 2023-01-07 14:04:02." }, "utcConfirmingTime": { "type": "string", "description": "UTC timestamp when on-chain transaction sync started, for example, 2023-01-07 14:04:02." }, "complianceStatus": { "type": "string", "description": "Compliance verification status: `ACCEPTED` approved, `PEND` pending, `REJECTED` rejected." }, "utcDoneTime": { "type": "string", "description": "UTC timestamp when the on-chain transaction was confirmed, for example, 2023-01-07 14:04:02." } } }, "RefundRequest": { "type": "object", "required": [ "refundRequestId", "prepayId", "refundAmount", "receiverId" ], "properties": { "prepayId": { "type": "string", "description": "The ID of the corresponding payment order" }, "refundAmount": { "type": "string", "description": "The amount to be refunded" }, "refundReason": { "type": "string", "description": "The reason for the refund" }, "receiverId": { "type": "integer", "description": "The Gate user ID of the recipient of the refund for address payment", "format": "int64" }, "refundRequestId": { "type": "string", "description": "Merchant refund request ID" } } }, "RefundResponse": { "type": "object", "description": "Standard response wrapper; business fields are under data", "properties": { "status": { "type": "string", "description": "Status", "example": "SUCCESS" }, "code": { "type": "string", "description": "Business code", "example": "000000" }, "errorMessage": { "type": "string", "description": "Error message" }, "data": { "$ref": "#/components/schemas/RefundData" } } }, "TransactionDetailResponse": { "type": "object", "description": "Response to request for querying on-chain transaction details", "properties": { "status": { "type": "string" }, "code": { "type": "string" }, "errorMessage": { "type": "string" }, "data": { "$ref": "#/components/schemas/TransactionDetailData" } } }, "TransactionDetailData": { "type": "object", "properties": { "prepayId": { "type": "string", "description": "Payment ID" }, "merchantId": { "type": "integer", "format": "int64", "description": "Gate UID used to apply for a merchant account" }, "merchantTradeNo": { "type": "string", "description": "Merchant system transaction number" }, "transactionId": { "type": "string", "description": "Transaction ID" }, "goodsName": { "type": "string", "description": "Name of the goods" }, "currency": { "type": "string", "description": "Order currency" }, "orderAmount": { "type": "string", "description": "Order amount" }, "payCurrency": { "type": "string", "description": "User payment currency" }, "payAmount": { "type": "string", "description": "Payment amount for the order" }, "status": { "type": "string", "description": "Order status" }, "utcCreateTime": { "type": "string", "description": "UTC expression of order creation time" }, "utcExpireTime": { "type": "string", "description": "UTC expression of order expiration time" }, "utcUpdateTime": { "type": "string", "description": "UTC expression of order status update time" }, "transactTime": { "type": "integer", "format": "int64", "description": "UTC millisecond timestamp of transaction completion in the background" }, "order_name": { "type": "string", "description": "Order name" }, "channelId": { "type": "string", "description": "Client Name" }, "transactionDetail": { "$ref": "#/components/schemas/TransactionDetail" } } }, "TransactionDetail": { "type": "object", "properties": { "inTerm": { "$ref": "#/components/schemas/TxDetail" }, "outOfTerm": { "$ref": "#/components/schemas/TxDetail" } } }, "TxDetail": { "type": "object", "properties": { "done": { "$ref": "#/components/schemas/TxDetailStateItem" }, "wait": { "$ref": "#/components/schemas/TxDetailStateItem" } } }, "TxDetailStateItem": { "type": "object", "properties": { "amount": { "type": "string", "description": "Total amount confirmed on chain" }, "txList": { "type": "array", "description": "List of payment records", "items": { "$ref": "#/components/schemas/TxItem" } } } }, "TxItem": { "type": "object", "properties": { "chain": { "type": "string", "description": "Name of the blockchain." }, "address": { "type": "string", "description": "The address." }, "fromAddress": { "type": "string", "description": "from address" }, "fullCurrType": { "type": "string", "description": "The name of the chain including network information." }, "amount": { "type": "string", "description": "The payment amount." }, "txId": { "type": "string", "description": "The transaction ID on the blockchain." }, "utcCreateTime": { "type": "string", "description": "The UTC timestamp when the payment record was detected on the blockchain, for example, 2023-01-07 14:04:02." }, "utcUpdateTime": { "type": "string", "description": "The UTC timestamp when the payment record status was updated on the blockchain, for example, 2023-01-07 14:04:02." }, "utcConfirmingTime": { "type": "string", "description": "UTC timestamp when compliance verification passed, for example, 2023-01-07 14:04:02. Returned when the compliance-passed event exists." }, "complianceStatus": { "type": "string", "description": "Compliance verification status: `ACCEPTED` approved, `PEND` pending, `REJECTED` rejected." }, "utcDoneTime": { "type": "string", "description": "UTC timestamp when the on-chain transaction was confirmed, for example, 2023-01-07 14:04:02. Returned when the on-chain confirmation event exists." } } }, "RefundData": { "type": "object", "description": "Address refund business data", "properties": { "refundRequestId": { "type": "string", "description": "Merchant's refund request id" }, "prepayId": { "type": "string", "description": "The id of the payment order to be refunded" }, "orderAmount": { "type": "string", "description": "The amount of the original payment order" }, "refundAmount": { "type": "string", "description": "The amount to be refunded" } } } }, "parameters": { "X-GatePay-Certificate-ClientId": { "name": "X-GatePay-Certificate-ClientId", "in": "header", "required": true, "description": "Merchant client ID, obtained from GatePay platform", "schema": { "type": "string" } }, "X-GatePay-Signature": { "name": "X-GatePay-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 signature for request validation", "schema": { "type": "string" } }, "X-GatePay-Timestamp": { "name": "X-GatePay-Timestamp", "in": "header", "required": true, "description": "Millisecond timestamp; the difference from server time must not exceed 30 seconds.", "schema": { "type": "string" } }, "X-GatePay-Nonce": { "name": "X-GatePay-Nonce", "in": "header", "required": true, "description": "Random nonce for replay attack prevention", "schema": { "type": "string" } } } } }