> ## 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 Web Payment Refund

> Query the status and details of a refund order by merchant-generated refund request ID.

## Overview

This page documents the `POST /v1/pay/order/refund/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.
* 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/web-payment-openapi.json POST /v1/pay/order/refund/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:
  /v1/pay/order/refund/query:
    post:
      tags:
        - web-payment
      summary: Query refund order
      description: >-
        Query the status and details of a refund order by merchant-generated
        refund request ID.
      operationId: queryRefund
      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/QueryRefundRequest'
            examples:
              default:
                summary: default
                value:
                  refundRequestId: '156123911'
      responses:
        '200':
          description: Refund order detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryRefundResponse'
              examples:
                success:
                  summary: Success response
                  value:
                    status: SUCCESS
                    code: '000000'
                    data:
                      refundRequestId: '156123911'
                      prepayId: '1647557960944'
                      orderAmount: '1.91'
                      refundAmount: '0.8'
                      refundStatus: SUCCESS
                    errorMessage: ''
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'
  schemas:
    QueryRefundRequest:
      type: object
      description: Request body for querying refund order.
      properties:
        refundRequestId:
          type: string
          description: >-
            Refund order ID generated by the merchant. Must be unique and no
            more than 32 characters.
      required:
        - refundRequestId
    QueryRefundResponse:
      type: object
      description: Response body for querying refund order.
      properties:
        status:
          type: string
          description: SUCCESS or FAIL
        code:
          type: string
          description: Error code
        errorMessage:
          type: string
          description: Error message
        data:
          type: object
          description: Refund order information
          properties:
            refundRequestId:
              type: string
              description: >-
                Merchant-generated refund request ID (must be unique and no more
                than 32 characters).
            prepayId:
              type: string
              description: ID of the completed payment order.
            orderAmount:
              type: string
              description: Order amount.
            refundAmount:
              type: string
              description: Refund amount, cannot exceed the total order amount.
            refundReason:
              type: string
              description: Refund reason, up to 256 characters.
          required:
            - refundRequestId
            - prepayId
            - orderAmount
            - refundAmount
      required:
        - status
        - code

````