{ "openapi": "3.1.0", "info": { "title": "GatePay OTC Fiat API", "description": "Reference for OTC fiat withdrawal and deposit APIs.", "version": "2.1.0" }, "servers": [ { "url": "https://openplatform.gateapi.io" } ], "paths": { "/withdraw/open/otc/api/v1/quote": { "post": { "summary": "Get OTC Off-ramp Quote", "description": "Get a fiat-to-crypto quote for the OTC off-ramp flow.", "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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } } } } }, "/withdraw/open/otc/api/order/create": { "post": { "summary": "Create OTC Withdrawal Order", "description": "Create an OTC withdrawal order after obtaining a quote.", "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/WithdrawalCreateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawalCreateResponse" } } } } } } }, "/withdraw/open/otc/api/order/detail": { "get": { "summary": "Query OTC Withdrawal Order Detail", "description": "Query the detail of an OTC withdrawal 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": "orderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gate OTC order ID." }, { "name": "clientOrderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant custom order ID." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } } } } }, "/withdraw/open/otc/api/order/list": { "post": { "summary": "Query OTC Withdrawal Order List", "description": "Query OTC withdrawal orders in batch.", "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/OrderListRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } } } } }, "/withdraw/open/otc/api/bank/country/list": { "get": { "summary": "Query Available Bank Countries", "description": "Query available countries for bank account registration.", "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/CountryListResponse" } } } } } } }, "/withdraw/open/otc/api/bank/create": { "post": { "summary": "Create Bank Account", "description": "Create a linked bank account for OTC settlement.", "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": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/BankCreateRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankCreateResponse" } } } } } } }, "/withdraw/open/otc/api/bank/list": { "get": { "summary": "Query Bank Account List", "description": "List linked bank accounts.", "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/BankListResponse" } } } } } } }, "/withdraw/open/otc/api/bank/delete": { "post": { "summary": "Delete Bank Account", "description": "Delete a linked bank account.", "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/BankDeleteRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } } } }, "delete": { "summary": "Delete Bank Account (DELETE)", "description": "Delete a bank account by using the DELETE method.", "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/BankDeleteRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" } } } } } } }, "/withdraw/open/otc/api/bank/material/supplement": { "post": { "summary": "Submit Bank Account Material Supplement", "description": "Submit additional KYC or compliance documents for an existing linked OTC bank account when GatePay requests a material supplement (for example after add-bank review or when the account is pending additional proof).", "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": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OtcBankMaterialSupplementRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankMaterialSupplementResponse" } } } } } } }, "/payment/open/otc/api/recharge": { "post": { "summary": "Create OTC Recharge Order", "description": "Create an OTC fiat recharge 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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeResponse" } } } } } } }, "/payment/open/otc/api/recharge/confirm": { "post": { "summary": "Confirm OTC Recharge Payment Completed", "description": "Notify the system that the merchant has completed the offline fiat transfer. This endpoint uses multipart/form-data. When generating the signature, use the plain text string “timestamp\\nnonce\\n\\n”, and do not append the multipart request body.", "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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeConfirmResponse" } } } } } } }, "/payment/open/otc/api/recharge/cancel": { "post": { "summary": "Cancel OTC Recharge Order", "description": "Cancel an OTC recharge order before payment is confirmed.", "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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeCancelResponse" } } } } } } }, "/payment/open/otc/api/recharge/detail": { "get": { "summary": "Query OTC Recharge Order Detail", "description": "Query detail for a fiat recharge 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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." }, { "name": "orderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Gate OTC order ID. At least one of orderId or clientOrderId is required." }, { "name": "clientOrderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Merchant custom order ID. At least one of orderId or clientOrderId is required." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeDetailResponse" } } } } } } }, "/payment/open/otc/api/recharge/list": { "get": { "summary": "Query OTC Recharge Order List", "description": "List OTC recharge orders. `startTime` and `endTime` are required.", "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": "X-GatePay-On-Behalf-Of", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Institutional sub-account UID. Only required when an institution submits a request on behalf of a sub-account; not required for direct merchant requests." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "PROCESSING", "DONE", "CANCEL", "ERROR" ] }, "description": "Filter by order status." }, { "name": "startTime", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "Start of the query time range (epoch millis). Required." }, { "name": "endTime", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "End of the query time range (epoch millis). Required." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Page number. Use -1 to fetch all records without pagination." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Number of records per page. Required when `page` >= 0. Max 1000." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcRechargeListResponse" } } } } } } } }, "components": { "parameters": { "X-GatePay-Certificate-ClientId": { "name": "X-GatePay-Certificate-ClientId", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Merchant application client ID used to identify the calling app." }, "X-GatePay-Signature": { "name": "X-GatePay-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "HMAC signature generated from the request according to GatePay signing rules." }, "X-GatePay-Timestamp": { "name": "X-GatePay-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Millisecond timestamp; the difference from server time must not exceed 30 seconds." }, "X-GatePay-Nonce": { "name": "X-GatePay-Nonce", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Random nonce used together with the timestamp to prevent replay attacks." } }, "schemas": { "QuoteRequest": { "type": "object", "properties": { "cryptoCurrency": { "type": "string", "description": "Cryptocurrency code used in the quote request. On-ramp supports: USDT, USDC. Off-ramp supports: USDT, USDC." }, "fiatCurrency": { "type": "string", "description": "Fiat currency code used in the quote request. Currently supported: USD." }, "cryptoAmount": { "type": "string", "description": "Cryptocurrency amount used when quoting by crypto amount." }, "fiatAmount": { "type": "string", "description": "Fiat amount used when quoting by fiat amount." }, "side": { "type": "string", "description": "Quote direction. Use CRYPTO to quote by crypto amount or FIAT to quote by fiat amount." }, "promotionCode": { "type": "string", "description": "Optional promotion code if supported by the OTC business flow." }, "type": { "type": "string", "description": "OTC business type. Use BUY for on-ramp and SELL for off-ramp." } }, "required": [ "cryptoCurrency", "fiatCurrency", "side", "type" ], "example": { "cryptoCurrency": "USDT", "fiatCurrency": "USD", "fiatAmount": "1000", "side": "FIAT", "type": "BUY" } }, "QuoteResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "quoteToken": { "type": "string", "description": "Quote token used when creating the OTC order." }, "validPeriod": { "type": "integer", "description": "Quote validity period in seconds." }, "cryptoAmount": { "type": "string", "description": "Quoted cryptocurrency amount." }, "fiatAmount": { "type": "string", "description": "Quoted fiat amount." }, "fiatRate": { "type": "string", "description": "Fiat rate expressed as fiat per crypto." }, "cryptoRate": { "type": "string", "description": "Crypto rate expressed as crypto per fiat." } }, "description": "Quote payload returned by the API." } }, "example": { "code": "0", "status": "success", "errorMessage": "", "data": { "quoteToken": "qt_01JXYZABCDEF", "validPeriod": 60, "cryptoAmount": "1088.42", "fiatAmount": "1000", "fiatRate": "0.918762", "cryptoRate": "1.088420" } } }, "WithdrawalCreateRequest": { "type": "object", "properties": { "quoteToken": { "type": "string", "description": "Quote token returned by the quote API." }, "bankAccountId": { "type": "string", "description": "Destination bank account ID for fiat settlement." }, "cryptoCurrency": { "type": "string", "description": "Cryptocurrency being sold. Currently supported: USDT, USDC." }, "fiatCurrency": { "type": "string", "description": "Fiat currency to be settled out. Currently supported: USD." }, "cryptoAmount": { "type": "string", "description": "Crypto amount for the withdrawal order." }, "fiatAmount": { "type": "string", "description": "Expected fiat settlement amount." }, "type": { "type": "string", "description": "Order type. Use SELL for off-ramp." }, "clientOrderId": { "type": "string", "description": "Merchant-defined unique order ID." } }, "required": [ "quoteToken", "bankAccountId", "cryptoCurrency", "fiatCurrency", "cryptoAmount", "fiatAmount", "type", "clientOrderId" ] }, "WithdrawalCreateResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "description": "Withdrawal order creation payload.", "properties": { "orderId": { "type": "string", "description": "Gate OTC order ID." }, "clientOrderId": { "type": "string", "description": "Merchant-defined order ID." }, "status": { "type": "string", "description": "Current order status. Available values: PROCESSING (in processing), DISPATCHED (payout dispatched), DONE (completed), FAIL (failed)." }, "createTime": { "type": "integer", "description": "Order creation timestamp." } } } }, "example": { "code": "000000", "status": "SUCCESS", "errorMessage": "", "data": { "orderId": "1234567890", "clientOrderId": "merchant_order_001", "status": "PROCESSING", "createTime": 1726055849126 } } }, "OrderRecord": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Gate OTC order ID." }, "status": { "type": "string", "description": "Current order status. Available values: PROCESSING (in processing), DISPATCHED (payout dispatched), DONE (completed), FAIL (failed)." }, "cryptoCurrency": { "type": "string", "description": "Cryptocurrency code." }, "fiatCurrency": { "type": "string", "description": "Fiat currency code." }, "cryptoAmount": { "type": "string", "description": "Cryptocurrency amount." }, "fiatAmount": { "type": "string", "description": "Fiat amount." }, "fiatRate": { "type": "string", "description": "Settlement fiat rate." }, "bankAccountId": { "type": "string", "description": "Bank account ID associated with the order." }, "clientOrderId": { "type": "string", "description": "Merchant-defined order ID." }, "type": { "type": "string", "description": "OTC order type such as BUY or SELL." }, "createTime": { "type": "integer", "description": "Order creation timestamp." }, "updateTime": { "type": "integer", "description": "Last update timestamp." }, "errMsg": { "type": "string", "description": "Failure reason." }, "tradeFee": { "type": "string", "description": "Fee amount." }, "finalFiatAmount": { "type": "string", "description": "Final settled fiat amount." }, "bankSlipInfo": { "type": "string", "description": "Bank slip information." }, "promCode": { "type": "string", "description": "Promotion code passed when creating the order." } } }, "OrderResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "$ref": "#/components/schemas/OrderRecord", "description": "Order detail payload." } } }, "OrderListRequest": { "type": "object", "properties": { "status": { "type": "string", "description": "Filter by order status. Available values: PROCESSING (in processing), DISPATCHED (payout dispatched), DONE (completed), FAIL (failed)." }, "type": { "type": "string", "description": "Filter by OTC order type." }, "cryptoCurrency": { "type": "string", "description": "Filter by cryptocurrency code." }, "fiatCurrency": { "type": "string", "description": "Filter by fiat currency code." }, "startTime": { "type": "string", "description": "Start of the query time range." }, "endTime": { "type": "string", "description": "End of the query time range." }, "page": { "type": "integer", "description": "Page number." }, "pageSize": { "type": "integer", "description": "Number of records per page." }, "clientOrderId": { "type": "string", "description": "Filter by merchant-defined order ID." } } }, "OrderListResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number." }, "pageSize": { "type": "integer", "description": "Number of records per page." }, "total": { "type": "integer", "description": "Total number of matching records." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderRecord" }, "description": "Order list data." } }, "description": "Paged order list payload." } } }, "CountryListResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "data": { "type": "array", "items": { "type": "object", "properties": { "countryId": { "type": "integer", "description": "Country ID." }, "countryName": { "type": "string", "description": "Country name in English." }, "countryCn": { "type": "string", "description": "Country name in Chinese." } } }, "description": "Supported country list." } } }, "BankCreateRequest": { "type": "object", "properties": { "bankAccountName": { "type": "string", "description": "Bank account name." }, "bankName": { "type": "string", "description": "Bank name." }, "countryId": { "type": "integer", "description": "Country ID." }, "address": { "type": "string", "description": "Bank address." }, "iban": { "type": "string", "description": "Account number or IBAN." }, "swift": { "type": "string", "description": "SWIFT." }, "remittanceLineNumber": { "type": "string", "description": "Routing or clearing code." }, "agentBankName": { "type": "string", "description": "Agent bank name." }, "agentBankSwift": { "type": "string", "description": "Agent bank SWIFT." }, "file": { "type": "string", "format": "binary", "description": "Bank statement file. The file must not exceed 4 MB and only jpg, jpeg, and png formats are accepted. Upload a bank statement issued within the last 3 months. The bank account name must exactly match the verified identity name. If there is any difference due to language or similar reasons, also provide supporting documents such as a bank certification letter, passport, or an official name-change receipt." } }, "required": [ "bankAccountName", "bankName", "countryId", "address", "iban", "swift", "file" ] }, "BankCreateResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message returned when the request fails." }, "data": { "type": "object", "properties": { "bankAccountId": { "type": "string", "description": "Bank account ID." }, "needSupplementMaterial": { "type": "boolean", "description": "Whether supplementary KYC or compliance materials are still required for this bank account. When `true`, submit the requested documents as prompted (for example with Submit Bank Account Material Supplement)." } }, "description": "Created bank account information." } }, "example": { "code": "000000", "data": { "bankAccountId": "2897434", "needSupplementMaterial": false }, "status": "SUCCESS", "errorMessage": "" } }, "BankDeleteRequest": { "type": "object", "properties": { "bankAccountId": { "type": "string", "description": "Bank account ID to delete." } }, "required": [ "bankAccountId" ] }, "OtcBankMaterialSupplementRequest": { "type": "object", "description": "Supplementary document upload for a linked bank account. See each property for the material type; `bankAccountId` targets the account.", "properties": { "bankAccountId": { "type": "string", "description": "Linked bank account ID (`bankAccountId` from Query Bank Account List or Create Bank Account)." }, "certificate": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Company registration / incorporation certificate, business license, or equivalent corporate identity documents.", "items": { "type": "string", "format": "binary" } }, "passport": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Passport or other government-issued ID for relevant individuals.", "items": { "type": "string", "format": "binary" } }, "shareHolders": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Shareholder register or ownership documentation.", "items": { "type": "string", "format": "binary" } }, "shareHoldingStructure": { "type": "array", "minItems": 1, "maxItems": 5, "description": "Shareholding / beneficial ownership structure chart.", "items": { "type": "string", "format": "binary" } }, "additional": { "type": "array", "maxItems": 5, "description": "Any other documents explicitly requested in the supplement notice.", "items": { "type": "string", "format": "binary" } } }, "required": [ "bankAccountId", "certificate", "passport", "shareHolders", "shareHoldingStructure" ] }, "BankMaterialSupplementResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "boolean", "description": "`true` when the supplementary materials have been accepted for processing; `false` otherwise. The final review outcome is still determined by the bank account status returned in Query Bank Account List." } } }, "BankListResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "data": { "type": "array", "items": { "type": "object", "properties": { "bankAccountId": { "type": "string", "description": "Bank account ID." }, "bankAccountName": { "type": "string", "description": "Bank account holder name." }, "bankName": { "type": "string", "description": "Bank name." }, "countryId": { "type": "integer", "description": "Country ID." }, "countryName": { "type": "string", "description": "Country name." }, "address": { "type": "string", "description": "Bank address." }, "iban": { "type": "string", "description": "IBAN or bank account number." }, "swift": { "type": "string", "description": "SWIFT or BIC code." }, "remittanceLineNumber": { "type": "string", "description": "Routing or clearing code." }, "agentBankName": { "type": "string", "description": "Agent bank name." }, "agentBankSwift": { "type": "string", "description": "Agent bank SWIFT." }, "status": { "type": "integer", "description": "Bank account review status. `1` = approved, `2` = pending review, `3` = pending supplementary materials, `99` = rejected.", "enum": [ 1, 2, 3, 99 ] }, "memo": { "type": "string", "description": "Memo entered by operations staff, typically returned as the rejection reason when the bank account review is rejected." } } }, "description": "Linked bank account list." } } }, "GenericSuccessResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "oneOf": [ { "type": "object", "additionalProperties": true, "description": "Business response payload." }, { "type": "string", "description": "Business response payload." } ], "description": "Business response payload." } } }, "OtcRechargeRequest": { "type": "object", "properties": { "quoteToken": { "type": "string", "description": "Quote token returned by the quote API." }, "bankId": { "type": "string", "description": "Merchant bank ID used for remittance." }, "currency": { "type": "string", "description": "Cryptocurrency to receive. Currently supported: USDT, USDC." }, "amount": { "type": "string", "description": "Cryptocurrency amount to be credited." }, "fiatCurrency": { "type": "string", "description": "Fiat currency to remit. Currently supported: USD." }, "fiatAmount": { "type": "string", "description": "Fiat amount to be paid." }, "promoCode": { "type": "string", "description": "Optional promotion code." } }, "required": [ "quoteToken", "bankId", "currency", "amount", "fiatCurrency", "fiatAmount" ], "example": { "quoteToken": "qt_01JXYZABCDEF", "bankId": "ba_123456789", "currency": "USDT", "amount": "1088.42", "fiatCurrency": "USD", "fiatAmount": "1000" } }, "OtcRechargeResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Gate OTC order ID." }, "otcOrderId": { "type": "string", "description": "OTC order ID." }, "currency": { "type": "string", "description": "Cryptocurrency code." }, "amount": { "type": "string", "description": "Cryptocurrency amount." }, "fiatCurrency": { "type": "string", "description": "Fiat currency code." }, "fiatAmount": { "type": "string", "description": "Fiat amount." }, "cfRate": { "type": "string", "description": "Exchange rate." }, "bankId": { "type": "string", "description": "Bank ID." }, "bankNumber": { "type": "string", "description": "Bank number." }, "paid": { "type": "boolean", "description": "Whether the order has been paid." }, "status": { "type": "string", "description": "Current order status." }, "card_info": { "$ref": "#/components/schemas/OtcCardInfo", "description": "Gate OTC collection bank information." }, "createTime": { "type": "integer", "format": "int64", "description": "Order creation timestamp (epoch millis)." }, "promoCode": { "type": "string", "description": "Promotion code." }, "transferRemark": { "type": "string", "description": "Required remittance remark." } } } } }, "OtcCardInfo": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Card info record ID." }, "uid": { "type": "integer", "format": "int64", "description": "Merchant UID." }, "entity": { "type": "string", "description": "Entity name." }, "bank_account_name": { "type": "string", "description": "Collection bank account holder name." }, "bank_name": { "type": "string", "description": "Collection bank name." }, "bank_country": { "type": "string", "description": "Collection bank country." }, "bank_address": { "type": "string", "description": "Collection bank address." }, "bank_code": { "type": "string", "description": "Bank code." }, "branch_code": { "type": "string", "description": "Branch code." }, "iban": { "type": "string", "description": "Collection IBAN or account number." }, "swift": { "type": "string", "description": "Collection SWIFT or BIC code." }, "remittance_line_number": { "type": "string", "description": "Bank routing or remittance line number." }, "agent_bank_name": { "type": "string", "description": "Agent bank name if applicable." }, "agent_bank_swift": { "type": "string", "description": "Agent bank SWIFT if applicable." }, "transferRemark": { "type": "string", "description": "Required remittance remark or payment reference." }, "memo": { "type": "string", "description": "Memo." }, "is_default": { "type": "boolean", "description": "Whether this is the default card." }, "bank_id": { "type": "string", "description": "Bank ID." } } }, "OtcRechargeConfirmResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the confirm operation succeeded." } } } } }, "OtcRechargeOrder": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Gate OTC order ID." }, "otcOrderId": { "type": "string", "description": "OTC order ID." }, "currency": { "type": "string", "description": "Cryptocurrency code." }, "amount": { "type": "string", "description": "Cryptocurrency amount." }, "fiatCurrency": { "type": "string", "description": "Fiat currency code." }, "fiatAmount": { "type": "string", "description": "Fiat amount." }, "cfRate": { "type": "string", "description": "Exchange rate." }, "bankId": { "type": "string", "description": "Bank ID." }, "bankNumber": { "type": "string", "description": "Bank number." }, "paid": { "type": "boolean", "description": "Whether the order has been paid." }, "status": { "type": "string", "description": "Current order status." }, "card_info": { "$ref": "#/components/schemas/OtcCardInfo", "description": "Gate OTC collection bank information." }, "createTime": { "type": "integer", "format": "int64", "description": "Order creation timestamp (epoch millis)." }, "promoCode": { "type": "string", "description": "Promotion code." }, "transferRemark": { "type": "string", "description": "Required remittance remark." }, "paymentReceiptFileUrl": { "type": "string", "description": "Payment receipt file URL." } } }, "OtcRechargeListResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64", "description": "Total number of matching records." }, "page": { "type": "integer", "format": "int64", "description": "Current page number." }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/OtcRechargeOrder" }, "description": "Order list data." } } } } }, "OtcRechargeDetailResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "$ref": "#/components/schemas/OtcRechargeOrder", "description": "Order detail payload." } } }, "OtcRechargeCancelResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "status": { "type": "string", "description": "Top-level request status." }, "errorMessage": { "type": "string", "description": "Error message when the request fails." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the cancel operation succeeded." } } } } }, "ConfirmRequest": { "type": "object", "properties": { "orderId": { "type": "string", "description": "OTC deposit order ID to confirm." }, "file": { "type": "string", "format": "binary", "description": "Payment receipt file. Max 4 MB. Supported formats: jpg, jpeg, png, pdf." } }, "required": [ "orderId", "file" ], "example": { "orderId": "71347515709194240", "file": "(binary)" } }, "CancelRequest": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID to cancel." } }, "required": [ "orderId" ], "example": { "orderId": "71347515709194240" } }, "CancelResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Business response code." }, "message": { "type": "string", "description": "Business response message." }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the cancel operation succeeded." } }, "description": "Business response payload." } }, "example": { "code": "0", "message": "success", "data": { "success": true } } }, "OtcCallbackPayload": { "type": "object", "properties": { "bizType": { "type": "string", "description": "Fixed OTC business type." }, "bizId": { "type": "string", "description": "OTC order ID." }, "bizStatus": { "type": "string", "description": "OTC callback business status.", "enum": [ "RECHARGE_SUCCESS", "RECHARGE_FAIL", "WITHDRAW_SUCCESS", "WITHDRAW_FAIL", "WITHDRAW_DISPATCHED" ] }, "clientId": { "type": "string", "description": "Merchant client ID." }, "client_id": { "type": "string", "description": "Alternate merchant client ID field used by some integrations." }, "data": { "type": "string", "description": "JSON string containing the order snapshot." } }, "required": [ "bizType", "bizId", "bizStatus", "data" ] }, "OtcCallbackResponse": { "type": "object", "description": "Response body returned by the merchant after receiving the notification.", "properties": { "returnCode": { "type": "string", "description": "Return status code; `SUCCESS` indicates successful processing." }, "returnMessage": { "type": "string", "description": "Return message; may be empty on success.", "nullable": true } }, "required": [ "returnCode" ] }, "OtcCallbackData": { "type": "object", "description": "Parsed OTC order snapshot from `data`.", "properties": { "orderId": { "type": "string", "description": "OTC 订单 ID。" }, "clientOrderId": { "type": "string", "description": "商户侧订单号。" }, "fiatRate": { "type": "string", "description": "法币汇率。" }, "type": { "type": "string", "description": "交易方向，如 BUY / SELL。" }, "fiatCurrency": { "type": "string", "description": "法币币种。" }, "fiatAmount": { "type": "string", "description": "法币金额。" }, "cryptoCurrency": { "type": "string", "description": "加密货币币种。" }, "cryptoAmount": { "type": "string", "description": "加密货币数量。" }, "updateTime": { "type": "string", "description": "更新时间（毫秒时间戳字符串）。" }, "tradeFee": { "type": "string", "description": "出金手续费（出金回调可选）。" }, "finalFiatAmount": { "type": "string", "description": "扣除手续费后的法币金额（出金回调可选）。" }, "bankSlipInfo": { "type": "string", "description": "银行回单信息或文件链接（出金回调可选）。" }, "errMsg": { "type": "string", "description": "错误信息（失败态可选）。" }, "promoCode": { "type": "string", "description": "优惠码（可选）。" } } } } }, "webhooks": { "otcCallbackWebhook": { "post": { "summary": "OTC Order Status Update Notification", "description": "OTC order result callback sent to the merchant callback URL for both on-ramp and off-ramp flows.", "operationId": "otcCallbackWebhookEn", "requestBody": { "description": "OTC order status callback notification structure", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcCallbackPayload" }, "examples": { "offrampDispatched": { "summary": "Off-ramp dispatched", "value": { "bizType": "OTC", "bizId": "79550727153516602", "bizStatus": "WITHDRAW_DISPATCHED", "clientId": "UGxnuTtJHDuXPjYm", "data": "{\"type\":\"SELL\",\"errMsg\":\"\",\"orderId\":\"79550727153516602\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"124710\",\"updateTime\":\"1779958032486\",\"bankSlipInfo\":\"https://gateio-payments.s3.ap-northeast-1.amazonaws.com/otc_trade_file/otc-trade-record-file43255011-d96f549e1869e47908db891fb512c308.pdf\",\"cryptoAmount\":\"124710\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146200\",\"cryptoCurrency\":\"USDT\",\"finalFiatAmount\":\"124710\"}" } }, "rechargeSuccess": { "summary": "On-ramp success", "value": { "bizType": "OTC", "bizId": "79550727153516601", "bizStatus": "RECHARGE_SUCCESS", "clientId": "UGxnuTtJHDuXPjYm", "data": "{\"type\":\"BUY\",\"errMsg\":\"\",\"orderId\":\"79550727153516601\",\"fiatRate\":\"1\",\"promoCode\":\"\",\"fiatAmount\":\"10000\",\"updateTime\":\"1779958032486\",\"cryptoAmount\":\"10000\",\"fiatCurrency\":\"USD\",\"clientOrderId\":\"PCC101800177995803114487146201\",\"cryptoCurrency\":\"USDT\",\"finalFiatAmount\":\"10000\"}" } } } } } }, "responses": { "200": { "description": "Returns HTTP 200 to indicate the notification has been received successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtcCallbackResponse" }, "examples": { "success": { "summary": "Successful acknowledgement", "value": { "returnCode": "SUCCESS", "returnMessage": "" } } } } } } } } } } }