> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Withdrawal Status

> Query the status and details of a batch withdrawal order and its sub-orders by batch ID and detail status.

## Overview

This page documents the `POST /withdraw/open/institution/v1/pay/payouts/detail` endpoint. The full schema, parameters, and examples are rendered from the linked OpenAPI definition above.

## Notes

* Authentication uses the standard GatePay signed headers.
* This page documents the institution-path variant of the same API.
* Institution requests must include `X-GatePay-On-Behalf-Of` to indicate the initiating account context for the delegated request.
* For shared signing rules, see [/api-reference/version/100/en/common/securityAndSignature](/api-reference/version/100/en/common/securityAndSignature).

## Institution Notes

* Institutional requests must include `X-GatePay-On-Behalf-Of` to specify the institutional sub-account to operate on.


## OpenAPI

````yaml /api-reference/version/100/en/openapi/institution/withdraw-openapi.json POST /payment/open/institution/v1/pay/withdraw/query
openapi: 3.1.0
info:
  title: GatePay Withdrawal & Wallet API
  version: 1.0.0
  description: >-
    OpenAPI 3.1 specification for GatePay withdrawal and wallet APIs, based on
    the English withdrawal documentation. It covers batch withdrawals,
    withdrawal status query, supported chains by currency, total balance query,
    and withdrawal fee query.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths:
  /payment/open/institution/v1/pay/withdraw/query:
    post:
      tags:
        - withdraw
      summary: Query withdrawal order status
      description: >-
        Query the status and details of a batch withdrawal order and its
        sub-orders by batch ID and detail status.
      operationId: queryWithdrawBatch
      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/WithdrawQueryRequest'
            examples:
              default:
                summary: Query all sub-orders under a batch
                value:
                  batch_id: '237394559478075555'
                  detail_status: ALL
      responses:
        '200':
          description: Withdrawal batch details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WithdrawQueryResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: SUCCESS
                    code: '000000'
                    errorMessage: ''
                    data:
                      batch_id: '237394559478075350'
                      merchant_id: 10002
                      client_id: mZ96D37oKk-HrWJc
                      status: FAIL
                      create_time: 1726055849126
                      channel_id: '123456'
                      withdraw_list:
                        - id: 35
                          batch_id: '237394559478075350'
                          merchant_id: 10002
                          suborder_id: '268830764354768896'
                          chain: ETH
                          address: '0x1234567890abcdef'
                          currency: USDT
                          amount: '1'
                          fee: '0'
                          tx_id: ''
                          timestamp: 0
                          memo: Payment for services-1
                          status: FAIL
                          merchant_withdraw_id: M137394559478075550
                          err_msg: unexpected http code error
                          client_id: mZ96D37oKk-HrWJc
                          create_time: 1726055848856
                          update_time: 1726055856011
                          channel_id: '123456'
                          fee_type: 1
                          done_amount: '1'
                        - id: 36
                          batch_id: '237394559478075350'
                          merchant_id: 10002
                          suborder_id: '268830764354768897'
                          chain: ETH
                          address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
                          currency: USDT
                          amount: '0.001'
                          fee: '0'
                          tx_id: ''
                          timestamp: 0
                          memo: Payment for services-1
                          status: FAIL
                          merchant_withdraw_id: M137394559478075551
                          err_msg: unexpected http code error
                          client_id: mZ96D37oKk-HrWJc
                          create_time: 1726055848856
                          update_time: 1726055856010
                          channel_id: '123456'
                          fee_type: 1
                          done_amount: '0.001'
                emptyData:
                  summary: Batch ID not found
                  value:
                    status: SUCCESS
                    code: '000000'
                    errorMessage: ''
                    data:
                      batch_id: '237394559478075358'
                      merchant_id: 0
                      client_id: ''
                      status: ''
                      create_time: 0
                      withdraw_list: []
components:
  parameters:
    X-GatePay-Certificate-ClientId:
      name: X-GatePay-Certificate-ClientId
      in: header
      required: true
      description: >-
        The clientId assigned when the merchant registers an application in the
        Gate merchant console.
      schema:
        type: string
        example: 4186d0c6-6a35-55a9-8dc6-5312769dbff8
    X-GatePay-Signature:
      name: X-GatePay-Signature
      in: header
      required: true
      description: >-
        Request signature. GatePay uses this signature to verify whether the
        request is valid.
      schema:
        type: string
    X-GatePay-Timestamp:
      name: X-GatePay-Timestamp
      in: header
      required: true
      description: >-
        UTC timestamp in milliseconds when the request is generated. GatePay
        will not process requests where the difference from the receive time
        exceeds 10 seconds.
      schema:
        type: string
        example: '1672905655498'
    X-GatePay-Nonce:
      name: X-GatePay-Nonce
      in: header
      required: true
      description: >-
        Random string. Must comply with HTTP header rules; recommended length is
        within 32 characters, composed of digits and letters.
      schema:
        type: string
        example: '9578'
  schemas:
    WithdrawQueryRequest:
      type: object
      description: Request body for querying batch withdrawal status.
      properties:
        batch_id:
          type: string
          description: Unique batch ID generated by the merchant at /v1/pay/withdraw.
        detail_status:
          type: string
          description: >-
            Query status of sub-orders  <br> ALL: all sub-orders <br>INIT ：new
            added sub-orders <br>PENDING: pending sub-orders <br>PROCESSING:
            submitted withdrawal request, pending confirmation <br>CHECK: in
            review <br>FAIL: failed sub-orders <br>DONE: successful sub-orders.
      required:
        - batch_id
        - detail_status
    WithdrawQueryResponse:
      type: object
      description: Response body for querying batch withdrawal status.
      properties:
        status:
          type: string
          description: >-
            Main order status: INIT (newly created order), PROCESSING (newly
            created payout order is in processing), PARTIAL (partially
            successful), FAIL (fully failed), SUCCESS (fully successful)
        code:
          type: string
          description: Error code
        errorMessage:
          type: string
          description: Error message
        data:
          type: object
          description: Batch withdrawal details
          properties:
            batch_id:
              type: string
              description: Batch ID.
            merchant_id:
              type: integer
              format: int64
              description: Merchant ID.
            client_id:
              type: string
              description: Client ID.
            status:
              type: string
              description: >-
                Main order status: INIT (newly created order), PROCESSING (newly
                created payout order is in processing), PARTIAL (partially
                successful), FAIL (fully failed), SUCCESS (fully successful).
            create_time:
              type: integer
              format: int64
              description: Main order creation time.
            channel_id:
              type: string
              description: Customer channel name.
            withdraw_list:
              type: array
              description: Sub-order information.
              items:
                $ref: '#/components/schemas/WithdrawSubOrder'
      required:
        - status
        - code
    WithdrawSubOrder:
      type: object
      description: Details of a withdrawal sub-order.
      properties:
        id:
          type: integer
          format: int64
          description: Record ID.
        batch_id:
          type: string
          description: Merchant batch withdrawal ID.
        merchant_id:
          type: integer
          format: int64
          description: Merchant ID.
        channel_id:
          type: string
          description: Customer channel name.
        suborder_id:
          type: string
          description: Sub-order ID generated by GatePay.
        withdraw_id:
          type: string
          description: Withdrawal transaction ID, used to query withdrawal order.
        chain:
          type: string
          description: Blockchain network.
        address:
          type: string
          description: Withdrawal address.
        currency:
          type: string
          description: Currency.
        amount:
          type: string
          format: decimal
          description: Initiated withdrawal amount.
        fee:
          type: string
          format: decimal
          description: Fee amount.
        tx_id:
          type: string
          description: Blockchain transaction hash.
        timestamp:
          type: integer
          format: int64
          description: Deposit/withdrawal operation time.
        memo:
          type: string
          description: Transfer memo and other note information.
        status:
          type: string
          description: >-
            Sub-order status: INIT (newly created sub-order), PENDING (order
            created, pending processing), PROCESSING (order is being processed),
            CHECK (under review), FAIL (withdrawal failed), DONE (withdrawal
            successful)
        merchant_withdraw_id:
          type: string
          description: Merchant withdrawal ID.
        err_msg:
          type: string
          description: Reason for withdrawal failure.
        create_time:
          type: integer
          format: int64
          description: Creation time.
        update_time:
          type: integer
          format: int64
          description: Update time.
        fee_type:
          type: integer
          description: >-
            Fee type: 0 - amount is deduction amount, 1 - amount is received
            amount.
        batch_withdraw_id:
          type: string
          description: Batch withdrawal ID (deprecated).
        desc:
          type: string
          description: Customer channel remarks.
        reconciliation_status:
          type: integer
          description: >-
            Withdrawal reconciliation status: 0 - not reconciled, 1 - in
            progress, 2 - match failed, 3 - match succeeded.
        is_placed:
          type: integer
          description: 'Whether the order has been placed: 0 - not placed, 1 - placed.'
        finish_time:
          type: integer
          format: int64
          description: Order completion time.
        sub_amount:
          type: string
          format: decimal
          description: Total deduction amount (fee amount + received amount).
        done_amount:
          type: string
          format: decimal
          description: Actual received amount.

````