openapi: 3.0.3
info:
  title: Payment Gateway API
  version: 0.1.0
  description: Initial API contract for the payment gateway platform.
servers:
  - url: /api/payment
paths:
  /health.php:
    get:
      summary: Service health
      responses:
        "200":
          description: Healthy
  /oauth.php:
    get:
      summary: Inspect merchant dashboard session
      parameters:
        - name: action
          in: query
          required: false
          schema:
            type: string
            default: me
      responses:
        "200":
          description: Merchant session data
    post:
      summary: Merchant dashboard login / refresh / logout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
      responses:
        "200":
          description: Token response
  /merchants.php:
    get:
      summary: List or fetch merchants
      parameters:
        - name: merchant_uid
          in: query
          required: false
          schema:
            type: string
        - name: merchant_code
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            default: all
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Merchant data
    post:
      summary: Register merchant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantCreateRequest'
      responses:
        "201":
          description: Merchant created
    patch:
      summary: Update merchant as admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantUpdateRequest'
      responses:
        "200":
          description: Merchant updated
  /payments.php:
    get:
      summary: List or fetch payments
      parameters:
        - name: payment_uid
          in: query
          required: false
          schema:
            type: string
        - name: payment_reference
          in: query
          required: false
          schema:
            type: string
        - name: merchant_order_id
          in: query
          required: false
          schema:
            type: string
        - name: merchant_uid
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            default: all
        - name: method
          in: query
          required: false
          schema:
            type: string
            default: all
      responses:
        "200":
          description: Payment data
    post:
      summary: Create, cancel, void, or inquire a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentActionRequest'
      responses:
        "200":
          description: Payment updated
        "201":
          description: Payment created
  /refunds.php:
    get:
      summary: List refunds
      responses:
        "200":
          description: Refund data
    post:
      summary: Create refund
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundCreateRequest'
      responses:
        "201":
          description: Refund created
  /webhooks.php:
    get:
      summary: List webhook endpoints
      responses:
        "200":
          description: Webhook data
    post:
      summary: Register webhook endpoint or receive provider callback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookActionRequest'
      responses:
        "200":
          description: Webhook processed
        "201":
          description: Webhook endpoint created
  /settlements.php:
    get:
      summary: List settlement batches
      responses:
        "200":
          description: Settlement data
    post:
      summary: Create or update settlement batches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementActionRequest'
      responses:
        "200":
          description: Settlement updated
        "201":
          description: Settlement created
  /dashboard.php:
    get:
      summary: Dashboard metrics
      parameters:
        - name: range
          in: query
          required: false
          schema:
            type: string
            default: 30d
      responses:
        "200":
          description: Dashboard data
  /simulator.php:
    get:
      summary: List payments for provider simulation
      parameters:
        - name: payment_uid
          in: query
          required: false
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
            default: all
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Simulator data
    post:
      summary: Simulate provider callback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulatorRequest'
      responses:
        "200":
          description: Simulation result
        "201":
          description: Simulation result
components:
  schemas:
    OAuthTokenRequest:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          type: string
          enum:
            - password
            - refresh_token
            - logout
        merchant_code:
          type: string
        email:
          type: string
        password:
          type: string
        refresh_token:
          type: string
    MerchantCreateRequest:
      type: object
      required:
        - legal_name
        - display_name
        - email
      properties:
        legal_name:
          type: string
        display_name:
          type: string
        email:
          type: string
        phone:
          type: string
        tax_id:
          type: string
        country_code:
          type: string
        settlement_schedule:
          type: string
        callback_url:
          type: string
        webhook_url:
          type: string
        per_transaction_limit:
          type: number
        daily_limit:
          type: number
        monthly_limit:
          type: number
        foreign_customer_limit:
          type: number
        allow_foreign_customer:
          type: boolean
        owner_email:
          type: string
        owner_name:
          type: string
        owner_password:
          type: string
        metadata:
          type: object
    MerchantUpdateRequest:
      type: object
      properties:
        status:
          type: string
        kyc_status:
          type: string
        kyb_status:
          type: string
        settlement_schedule:
          type: string
        per_transaction_limit:
          type: number
        daily_limit:
          type: number
        monthly_limit:
          type: number
        foreign_customer_limit:
          type: number
        allow_foreign_customer:
          type: boolean
        callback_url:
          type: string
        webhook_url:
          type: string
        risk_score:
          type: number
        notes:
          type: string
        metadata:
          type: object
    PaymentActionRequest:
      oneOf:
        - $ref: '#/components/schemas/PaymentCreateRequest'
        - $ref: '#/components/schemas/PaymentControlRequest'
    PaymentCreateRequest:
      type: object
      required:
        - amount
      properties:
        action:
          type: string
          example: create
        amount:
          type: number
        currency:
          type: string
          default: THB
        payment_method_code:
          type: string
          default: promptpay
        qr_type:
          type: string
          enum: [static, dynamic]
        merchant_order_id:
          type: string
        description:
          type: string
        customer_name:
          type: string
        customer_ref:
          type: string
        callback_url:
          type: string
        webhook_url:
          type: string
        country_code:
          type: string
        customer_ip:
          type: string
        device_fingerprint:
          type: string
        expires_in_minutes:
          type: integer
        idempotency_key:
          type: string
        metadata:
          type: object
    PaymentControlRequest:
      type: object
      required:
        - action
        - payment_uid
      properties:
        action:
          type: string
          enum: [cancel, void, inquiry, check_status]
        payment_uid:
          type: string
        reason:
          type: string
    RefundCreateRequest:
      type: object
      required:
        - payment_uid
      properties:
        payment_uid:
          type: string
        payment_reference:
          type: string
        merchant_order_id:
          type: string
        amount:
          type: number
        reason:
          type: string
        idempotency_key:
          type: string
    WebhookActionRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [register, provider]
        endpoint_url:
          type: string
        event_filters:
          oneOf:
            - type: array
              items:
                type: string
            - type: string
        status:
          type: string
        provider_code:
          type: string
        payment_uid:
          type: string
        payment_reference:
          type: string
        merchant_order_id:
          type: string
        provider_reference:
          type: string
        event_type:
          type: string
        raw:
          type: object
    SettlementActionRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
          enum: [create_batch, hold, release, reverse]
        merchant_uid:
          type: string
        settlement_type:
          type: string
        scheduled_for:
          type: string
          format: date-time
        notes:
          type: string
        metadata:
          type: object
    SimulatorRequest:
      type: object
      required:
        - action
        - payment_uid
      properties:
        action:
          type: string
          enum:
            - simulate
        payment_uid:
          type: string
        payment_reference:
          type: string
        merchant_order_id:
          type: string
        provider_code:
          type: string
          default: promptpay
        status:
          type: string
        provider_reference:
          type: string
        dispatch_webhooks:
          type: boolean
