> ## 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 Order Status

> Query the status and detailed information of an order.

## Overview

This page documents the `POST /payment/open/institution/v1/pay/order/query` 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 standard merchant endpoint.
* This endpoint returns the order-query payload directly and does not use the outer `bizType` / `bizStatus` callback envelope.
* For centralized payment orders, interpret `pay_amount` together with `orderAmount`.
* 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/web-payment-openapi.json POST /payment/open/institution/v1/pay/order/query
openapi: 3.1.0
info:
  title: GatePay Web Payment API
  version: 1.0.0
  description: >-
    OpenAPI 3.1 specification for GatePay Web payment APIs, based on the English
    Web Payment documentation. It includes creating prepay orders, closing
    orders, querying order status, and refund-related APIs.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
tags:
  - name: web-payment
    description: >-
      Web payment related APIs, including creating, closing, querying prepay
      orders and processing refunds.
paths:
  /payment/open/institution/v1/pay/order/query:
    post:
      tags:
        - web-payment
      summary: Query order status
      description: Query the status and detailed information of an order.
      operationId: queryOrder
      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'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryOrderRequest'
            examples:
              default:
                summary: default
                value:
                  merchantTradeNo: '56236'
      responses:
        '200':
          description: Order detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryOrderResponse'
              examples:
                success:
                  summary: Success response
                  description: >-
                    Example response for a settled order queried by settlement
                    currency.
                  value:
                    status: SUCCESS
                    code: '000000'
                    errorMessage: ''
                    data:
                      prepayId: '50620368071692288'
                      merchantId: 10002
                      merchantTradeNo: '4379824792349592345'
                      transactionId: ''
                      goodsName: NFT
                      currency: GT
                      orderAmount: '0.1'
                      status: EXPIRED
                      createTime: 1674030436229
                      expireTime: 1663054706000
                      transactTime: 0
                      order_name: MiniApp-Payment#4379824792349592345
                      pay_currency: ''
                      pay_amount: '0'
                      rate: '0'
                      channel_type: ''
                      inUsdt: ''
                      appLogo: >-
                        https://gimg2.gateimg.com/image/432c2715a0eaa6217af7a3db1e85ffc8dc866233.webp
                      appName: Latiago
                      channelId: '123456'
                      totalFeeAmount: '0'
                      totalSettleAmount: ''
                      payDetails: []
components:
  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
        example: 4186d0c6-6a35-55a9-8dc6-5312769dbff8
    X-GatePay-Signature:
      name: X-GatePay-Signature
      in: header
      required: true
      description: HMAC-SHA256 signature for request validation
      schema:
        type: string
        example: >-
          672d5650dcc9bb22ebf25fa16c28d03c0e159d742a9176d4340a5da326d75dc8a2ec24c97fa6fc5d1533dd6e968863747e1d86a45e562cbe899f9ed7e9ca7f77
    X-GatePay-Timestamp:
      name: X-GatePay-Timestamp
      in: header
      required: true
      description: Timestamp in milliseconds, must be within 5 minutes of server time
      schema:
        type: string
        example: '1672905655498'
    X-GatePay-Nonce:
      name: X-GatePay-Nonce
      in: header
      required: true
      description: Random nonce for replay attack prevention
      schema:
        type: string
        example: '3525756760'
    X-GatePay-On-Behalf-Of:
      name: X-GatePay-On-Behalf-Of
      in: header
      required: true
      schema:
        type: string
      description: >-
        Required delegated-subject header. Provide the initiating account ID for
        this request. For institution merchant APIs, this is typically the
        target sub-account ID; for institution charge and transfer APIs, it can
        be either an institution account ID or a sub-account ID.
  schemas:
    QueryOrderRequest:
      type: object
      description: >-
        Request body for querying order status. At least one of `prepayId` or
        `merchantTradeNo` must be provided.
      properties:
        prepayId:
          type: string
          description: Prepay ID.
        merchantTradeNo:
          type: string
          description: >-
            Merchant order ID. Either the prepay ID or this ID parameter must be
            provided.
    QueryOrderResponse:
      type: object
      description: Response body for querying order status.
      properties:
        status:
          type: string
          description: SUCCESS or FAIL
        code:
          type: string
          description: Error code
        errorMessage:
          type: string
          description: Error message, if any
        data:
          type: object
          description: Payment order information
          properties:
            prepayId:
              type: string
              description: Prepay ID
            merchantId:
              type: integer
              format: int64
              description: Gate UID used to apply for a merchant account
            merchantTradeNo:
              type: string
              description: Merchant order ID
            transactionId:
              type: string
              description: Transaction ID
            goodsName:
              type: string
              description: Goods name
            currency:
              type: string
              description: Order currency
            orderAmount:
              type: string
              description: Order amount
            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.
            status:
              type: string
              description: Order status
            createTime:
              type: integer
              format: int64
              description: Prepay creation time in milliseconds
            expireTime:
              type: integer
              format: int64
              description: Prepay expiration time in milliseconds
            transactTime:
              type: integer
              format: int64
              description: Payment completion time in milliseconds
            order_name:
              type: string
              description: Order name
            pay_currency:
              type: string
              description: Currency paid by the user
            pay_amount:
              type: string
              description: >-
                Payment amount; for centralized payment orders, this field
                represents the amount that should be paid and should be
                interpreted together with orderAmount
            expectCurrency:
              type: string
              description: >-
                Revenue currency specified when creating the order. Only
                returned in the order details with a specified settlement
                currency by the merchant.
            actualCurrency:
              type: string
              description: >-
                Currency actually settled to the merchant's account by the Gate
                backend after the order was paid. Only returned in the order
                details after Gate settles with the merchant.
            actualAmount:
              type: string
              description: >-
                Amount in the currency actually settled to the merchant's
                account by the Gate backend after the order was paid. Only
                returned in the order details after Gate settles with the
                merchant.
            rate:
              type: string
              description: Exchange rate for Convert payment.
            channelId:
              type: string
              description: Client Name.
            appName:
              type: string
              description: Application name
            appLogo:
              type: string
              description: Application logo
            inUsdt:
              type: string
              description: The corresponding USDT amount
            channel_type:
              type: string
              description: The channel type
            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.
            institutionFeeAmount:
              type: string
              description: >-
                Cumulative revenue-sharing amount charged. May be empty or `0`
                when payment flows are not settled, unpaid, or in
                centralized-payment-only scenarios.
            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'
          required:
            - prepayId
            - merchantId
            - merchantTradeNo
            - transactionId
            - goodsName
            - currency
            - orderAmount
            - status
            - createTime
            - expireTime
            - transactTime
            - order_name
            - pay_currency
            - pay_amount
            - rate
      required:
        - status
        - code
    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: Revenue-sharing amount.
        settleAmount:
          type: string
          description: Settled amount.
        settlementStatus:
          type: string
          description: 'Settlement status: `pending` not settled, `done` settled.'

````