> ## 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.

# Preview Merchant Fee

> This API is used to estimate the transaction fee amount based on merchant information, order amount, and other parameters. Only Gate Pay merchants can call this API.

## Overview

This page documents the `POST /payClearing/clearing/previewMerchantFee` 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/preview-merchant-fee-openapi.json POST /payClearing/clearing/previewMerchantFee
openapi: 3.1.0
info:
  title: GatePay API
  description: GatePay Payment Platform API - Estimate Merchant Fees
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://openplatform.gateapi.io
security: []
paths:
  /payClearing/clearing/previewMerchantFee:
    post:
      summary: Estimate Merchant Fees
      description: >-
        This API is used to estimate the transaction fee amount based on
        merchant information, order amount, and other parameters. Only Gate Pay
        merchants can call this API.
      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:
        description: Estimate merchant fee request parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewMerchantFeeRequest'
            examples:
              basicExample:
                summary: Basic Example
                value:
                  orderCurrency: USDT
                  accessMode: 0
                  scenario: 0
                  orderAmount: '100.00'
        required: true
      responses:
        '200':
          description: Estimation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewMerchantFeeResponse'
              examples:
                successResponse:
                  summary: Success Response
                  value:
                    status: success
                    code: '000000'
                    errorMessage: ''
                    data:
                      merchantId: '123456789'
                      merchantType: 1
                      accessMode: 0
                      orderCurrency: USDT
                      orderAmount: 100
                      orderFee: 2.5
        '400':
          description: Request parameter error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidParams:
                  summary: Invalid request parameters
                  value:
                    status: error
                    code: '400001'
                    errorMessage: Invalid request parameters
                    data: null
                invalidSignature:
                  summary: Invalid signature
                  value:
                    status: error
                    code: '400002'
                    errorMessage: Invalid signature
                    data: null
                invalidApiKey:
                  summary: API identity key not found or invalid
                  value:
                    status: error
                    code: '400004'
                    errorMessage: API identity key not found or invalid
                    data: null
                invalidClientId:
                  summary: INVALID_CLIENT_ID
                  value:
                    status: error
                    code: '400005'
                    errorMessage: INVALID_CLIENT_ID/Client ID error
                    data: null
                unsupportedMediaType:
                  summary: Unsupported media type
                  value:
                    status: error
                    code: '400007'
                    errorMessage: Unsupported media type
                    data: null
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                feeServiceError:
                  summary: Failed to call the fee calculation service
                  value:
                    status: error
                    code: '503011007'
                    errorMessage: Failed to call the fee calculation service
                    data: null
                feeConfigEmpty:
                  summary: Merchant fee configuration is empty
                  value:
                    status: error
                    code: '503011008'
                    errorMessage: Merchant fee configuration is empty
                    data: null
                unknownError:
                  summary: Unknown error
                  value:
                    status: error
                    code: '503010999'
                    errorMessage: Unknown error
                    data: null
components:
  parameters:
    X-GatePay-Certificate-ClientId:
      name: X-GatePay-Certificate-ClientId
      in: header
      required: true
      description: Merchant ID
      schema:
        type: string
        example: mZ96D37oKk-HrWJc
    X-GatePay-Signature:
      name: X-GatePay-Signature
      in: header
      required: true
      description: Signature
      schema:
        type: string
        example: >-
          601d560c54d53412aca5901256f101e7078b5779f61f30bedfe9a5f0b92f049589952a151ea477371e4a99ac0e1c3cc8dec62654b3c6a1794ef981efe19232bc
    X-GatePay-Timestamp:
      name: X-GatePay-Timestamp
      in: header
      required: true
      description: Timestamp (milliseconds)
      schema:
        type: string
        example: '1726027137585'
    X-GatePay-Nonce:
      name: X-GatePay-Nonce
      in: header
      required: true
      description: Nonce
      schema:
        type: string
        example: '2290830087'
  schemas:
    PreviewMerchantFeeRequest:
      type: object
      required:
        - orderCurrency
        - accessMode
        - scenario
        - orderAmount
      properties:
        orderCurrency:
          type: string
          description: Order currency, e.g., USDT, USDC, etc.
          example: USDT
        accessMode:
          type: integer
          description: 'Integration mode: 0=Gate Pay, 1=Web3 payment'
          enum:
            - 0
            - 1
          example: 0
        scenario:
          type: integer
          description: 'Transaction type (Scenario): 0=Collection'
          enum:
            - 0
          example: 0
        orderAmount:
          type: string
          format: decimal
          description: Order amount, must be greater than or equal to 0
          example: '100.00'
    PreviewMerchantFeeResponse:
      type: object
      properties:
        status:
          type: string
          description: 'Response status: success/error'
          enum:
            - success
            - error
          example: success
        code:
          type: string
          description: Response code, 000000 indicates success
          example: '000000'
        errorMessage:
          type: string
          description: Error message, empty on success
          example: ''
        data:
          $ref: '#/components/schemas/PreviewMerchantFeeData'
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          description: Response status
          enum:
            - error
          example: error
        code:
          type: string
          description: Error code
          example: '400001'
        errorMessage:
          type: string
          description: Error message
          example: Invalid request parameters
        data:
          type: 'null'
          description: Null on error
    PreviewMerchantFeeData:
      type: object
      properties:
        merchantId:
          type: string
          description: Merchant ID
          example: '123456789'
        merchantType:
          type: integer
          description: 'Merchant type: 0=NORMAL_MERCHANT, 1=AGENT'
          enum:
            - 0
            - 1
          example: 1
        accessMode:
          type: integer
          description: 'Integration mode: 0=Gate Pay, 1=Web3 payment'
          enum:
            - 0
            - 1
          example: 0
        orderCurrency:
          type: string
          description: Order currency
          example: USDT
        orderAmount:
          type: number
          format: decimal
          description: Order amount
          example: 100
        orderFee:
          type: number
          format: decimal
          description: Calculated fee
          example: 2.5

````