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

# api.php (order query/refund compatibility endpoint)

> Executes compatibility operations with `act`.
- `act=order`: query order status/result.
- `act=refund`: currently not supported; returns compatibility error message.

This endpoint also accepts GET with the same parameters.




## OpenAPI

````yaml /openapi.yaml post /epay/api.php
openapi: 3.1.0
info:
  title: Kyren Pay API
  description: >
    The Kyren Pay API enables merchants to accept payments from customers
    worldwide.

    Integrate checkout sessions, manage products, track orders, and handle
    webhooks.


    **Data types**: The API uses the following types for request/response data:

    - **string**: For text, identifiers, and **all amount/price fields** (e.g.
    `price`, `amount`, `platformFee`, `available`)
      to avoid floating-point precision issues. Use decimal format like `"9.99"`.
    - **integer**: For counts, pagination, and timestamps

    - **timestamp**: Unix timestamp in milliseconds (integer) for all time
    fields (e.g. `createdAt`, `paidAt`, `expiresAt`).
      Time parameters (e.g. `startDate`, `endDate`) also use Unix milliseconds.
  version: 1.0.0
  contact:
    name: Kyren Pay Support
    email: support@kyren.top
    url: https://kyren.top
servers:
  - url: https://api.kyren.top
    description: Production
  - url: https://staging-api.kyren.top
    description: Staging, available only with credentials issued by Kyren
security:
  - ApiKeyAuth: []
tags:
  - name: Config
    description: Retrieve platform configuration such as supported currencies.
  - name: Products
    description: Create and manage products that represent the goods or services you sell.
  - name: Checkouts
    description: Create checkout sessions to collect payments from your customers.
  - name: Orders
    description: View and manage orders created from completed checkout sessions.
  - name: Balance
    description: View your account balance and transaction history.
  - name: Epay Compatibility
    description: >
      Compatibility endpoints for existing integrations built on 易支付 API
      conventions.

      These endpoints use form/query parameters with `pid + sign` verification
      (MD5), not `x-api-key` header auth.
paths:
  /epay/api.php:
    post:
      tags:
        - Epay Compatibility
      summary: api.php (order query/refund compatibility endpoint)
      description: >
        Executes compatibility operations with `act`.

        - `act=order`: query order status/result.

        - `act=refund`: currently not supported; returns compatibility error
        message.


        This endpoint also accepts GET with the same parameters.
      operationId: callEpayApi
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EpayApiRequest'
            examples:
              queryOrder:
                summary: Query by out_trade_no
                value:
                  act: order
                  pid: merch_001
                  key: merchant_raw_api_key
                  out_trade_no: order_20260409002
              refund:
                summary: Refund (unsupported currently)
                value:
                  act: refund
                  pid: merch_001
                  key: merchant_raw_api_key
                  trade_no: order_epay_001
      responses:
        '200':
          description: Epay-compatible operation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpayApiResponse'
              examples:
                orderSuccess:
                  summary: Successful order query
                  value:
                    code: 1
                    msg: 查询订单号成功！
                    trade_no: order_epay_001
                    out_trade_no: order_20260409002
                    type: wxpay
                    pid: merch_001
                    addtime: '2026-04-09 06:10:20'
                    endtime: '2026-04-09 06:11:08'
                    name: AI Credits 1000
                    money: '9.99'
                    status: 1
                    param: user_42
                    buyer: ''
                refundUnsupported:
                  summary: Refund not supported
                  value:
                    code: 0
                    msg: 退款功能暂不支持，请联系客服
                error:
                  summary: Generic error
                  value:
                    code: 0
                    msg: 订单不存在
      security: []
components:
  schemas:
    EpayApiRequest:
      type: object
      required:
        - act
        - pid
        - key
      properties:
        act:
          type: string
          enum:
            - order
            - refund
          description: API action. `refund` currently returns unsupported message.
        pid:
          type: string
          description: Merchant ID
        key:
          type: string
          description: Merchant raw API key (not encrypted key)
        out_trade_no:
          type: string
          description: Merchant order number. Required when `trade_no` is not provided.
        trade_no:
          type: string
          description: Platform order ID. Required when `out_trade_no` is not provided.
    EpayApiResponse:
      oneOf:
        - $ref: '#/components/schemas/EpayOrderQuerySuccessResponse'
        - $ref: '#/components/schemas/EpaySimpleResponse'
    EpayOrderQuerySuccessResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 1
        msg:
          type: string
        trade_no:
          type: string
        out_trade_no:
          type: string
        type:
          $ref: '#/components/schemas/EpayPaymentType'
        pid:
          type: string
        addtime:
          type: string
          description: UTC datetime string, format `yyyy-MM-dd HH:mm:ss`
        endtime:
          type: string
          description: UTC datetime string, empty when unpaid
        name:
          type: string
        money:
          type: string
        status:
          type: integer
          enum:
            - 0
            - 1
          description: 1 means paid/settled; 0 means not paid
        param:
          type: string
        buyer:
          type: string
          description: Reserved field, currently empty string
    EpaySimpleResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 0
        msg:
          type: string
    EpayPaymentType:
      type: string
      enum:
        - alipay
        - wxpay
        - creditcard
        - crypto
        - paynow
      description: Payment channel type in Epay compatibility mode.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Your API key. Public production API-key endpoints accept `kyren_live_*`
        keys. Staging credentials are environment-specific and must be used only
        with the staging environment for which Kyren issued them.

````