> ## 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 Merchant Batch Transfer Order

> Query a merchant batch transfer order and its sub-order statuses by batch_id or merchant_batch_no.

## Overview

This page documents the `POST /v1/pay/batch/transfer/query` endpoint, which queries a merchant batch transfer order and its sub-order statuses. The full request schema, response structure, and examples are rendered from the linked OpenAPI definition above.

## Notes

* Authentication uses the standard GatePay signed headers.
* This endpoint is grouped under `Payout` → `Reward Distribution` in institution merchant APIs.
* `X-GatePay-On-Behalf-Of` is optional for this endpoint. Pass it only when you need to specify the initiating account context in an institution-delegated scenario.
* For shared signing rules, see [/api-reference/version/100/en/common/securityAndSignature](/api-reference/version/100/en/common/securityAndSignature).


## OpenAPI

````yaml api-reference/version/100/en/openapi/institution/withdraw-openapi.json POST /v1/pay/batch/transfer/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:
  /v1/pay/batch/transfer/query:
    post:
      tags:
        - reward-distribution
      summary: Query merchant batch transfer order
      description: >-
        Query a merchant batch transfer order and its sub-order statuses by
        batch_id or merchant_batch_no.
      operationId: queryMerchantBatchTransfer
      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'
        - $ref: '#/components/parameters/X-GatePay-On-Behalf-Of-Optional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RewardDistributionQueryRequest'
            examples:
              default:
                summary: Default example
                value:
                  merchant_batch_no: RB202606300001
                  detail_status: ALL
      responses:
        '200':
          description: Batch transfer order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardDistributionQueryResponse'
              examples:
                success:
                  summary: Queried successfully
                  value:
                    status: SUCCESS
                    code: '000000'
                    errorMessage: ''
                    data:
                      batch_id: '237394559478075550'
                      merchant_id: 10002
                      merchant_batch_no: RB202606300001
                      status: SUCCESS
                      currency: USDT
                      channel_id: '123456'
                      orders_list:
                        - receiver_id: 100001
                          amount: '12.5'
                          currency: USDT
                          status: SUCCESS
                          reward_id: reward_001
                          transaction_id: '0xabc123'
                          create_time: 1751263200000
                          channel_id: '123456'
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'
    X-GatePay-On-Behalf-Of-Optional:
      name: X-GatePay-On-Behalf-Of
      in: header
      required: false
      schema:
        type: string
      description: >-
        Optional delegated-subject header. Pass the initiating account ID only
        when an institution-delegated context needs to be identified; otherwise
        this header can be omitted.
  schemas:
    RewardDistributionQueryRequest:
      type: object
      description: Request body for querying a merchant batch transfer order.
      properties:
        batch_id:
          type: string
          description: >-
            GatePay batch ID. Either batch_id or merchant_batch_no can be
            provided.
        merchant_batch_no:
          type: string
          description: >-
            Merchant batch number. Either merchant_batch_no or batch_id can be
            provided.
        detail_status:
          type: string
          description: 'Sub-order status filter: ALL, PROCESSING, SUCCESS, FAIL.'
    RewardDistributionQueryResponse:
      type: object
      description: Response body for querying a merchant batch transfer order.
      properties:
        status:
          type: string
          description: API response result, SUCCESS or FAIL.
        code:
          type: string
          description: Response error code.
        errorMessage:
          type: string
          description: Error description.
        data:
          $ref: '#/components/schemas/RewardDistributionQueryResult'
      required:
        - status
        - code
    RewardDistributionQueryResult:
      type: object
      properties:
        batch_id:
          type: string
          description: Batch ID.
        merchant_id:
          type: integer
          format: int64
          description: Merchant ID.
        merchant_batch_no:
          type: string
          description: Merchant batch number.
        status:
          type: string
          description: Batch status, such as PROCESSING, SUCCESS, or FAIL.
        currency:
          type: string
          description: Batch currency.
        channel_id:
          type: string
          description: Channel ID.
        orders_list:
          type: array
          description: List of sub-orders.
          items:
            $ref: '#/components/schemas/RewardDistributionOrderResult'
    RewardDistributionOrderResult:
      type: object
      properties:
        receiver_id:
          type: integer
          format: int64
          description: Receiver user ID.
        amount:
          type: string
          description: Transfer amount.
        currency:
          type: string
          description: Currency.
        status:
          type: string
          description: 'Sub-order status: PROCESSING, SUCCESS, or FAIL.'
        reward_id:
          type: string
          description: Reward identifier or business-side sub-order identifier.
        transaction_id:
          type: string
          description: Transaction ID.
        create_time:
          type: integer
          format: int64
          description: Creation time.
        channel_id:
          type: string
          description: Channel ID.

````