openapi: 3.0.3
info:
  title: PayGlobe Payment Gateway API
  description: |
    Dual Payment Gateway supporting credit card payments (IGFS) and meal vouchers (Monni).

    ## Authentication
    All API requests require an API key in the Authorization header:
    ```
    Authorization: Bearer pk_test_PayGlobe123456789TestPublishable
    ```

    ## Test Keys
    - Publishable: `pk_test_PayGlobe123456789TestPublishable`
    - Secret: `sk_test_PayGlobe123456789TestSecret`
  version: 1.0.0
  contact:
    name: PayGlobe Support
    email: support@payglobe.com
servers:
  - url: https://api.payglobe.it/paymentgw
    description: Production server
  - url: http://localhost:8080/paymentgw
    description: Development server

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: API key authentication (pk_test_xxx or pk_live_xxx)

  schemas:
    PaymentInitiateRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          format: double
          example: 150.00
          description: Total amount to charge in EUR
        email:
          type: string
          format: email
          example: "customer@example.com"
          description: Customer email address for payment receipt (recommended)
        description:
          type: string
          example: "Order #12345"
          description: Optional order number or payment description

    PaymentInitiateResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        transactionId:
          type: string
          example: "abc-123-def-456"
        totalAmount:
          type: number
          format: double
          example: 150.00
        redirectUrl:
          type: string
          example: "https://paymentpage.igfs.payglobe.com?paymentID=XYZ"
          description: URL to redirect user for card payment
        igfs:
          type: object
          properties:
            paymentId:
              type: string
            status:
              type: string
              enum: [PENDING, SUCCESS, FAILED]

    TransactionStatusResponse:
      type: object
      properties:
        success:
          type: boolean
        transactionId:
          type: string
        status:
          type: string
          enum:
            - INITIALIZED
            - IGFS_PREAUTH_SUCCESS
            - IGFS_PREAUTH_FAILED
            - VOUCHER_PROCESSING
            - COMPLETED
            - FAILED
        totalAmount:
          type: number
          format: double
        breakdown:
          type: object
          properties:
            cardAmount:
              type: number
              format: double
            voucherAmount:
              type: number
              format: double
            paymentMethod:
              type: string
              enum: [CARD_ONLY, VOUCHER_ONLY, CARD_AND_VOUCHER]

    PaymentNotification:
      type: object
      description: Webhook notification sent to merchant's webhook URL
      properties:
        transactionId:
          type: string
        totalAmount:
          type: number
          format: double
        cardAmount:
          type: number
          format: double
        voucherAmount:
          type: number
          format: double
        paymentMethod:
          type: string
          enum: [CARD_ONLY, VOUCHER_ONLY, CARD_AND_VOUCHER]
        status:
          type: string
        completedAt:
          type: string
          format: date-time
        sessionDurationSeconds:
          type: integer
        cardGatewayDetails:
          type: object
          properties:
            paymentId:
              type: string
            operationType:
              type: string
              enum: [PREAUTHORIZATION, CAPTURE, REVERSAL]
        voucherDetails:
          type: object
          properties:
            serialNumber:
              type: string
            operationNumber:
              type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer

paths:
  /api/payment/initiate:
    post:
      summary: Initialize Payment
      description: |
        Initialize a new payment transaction. This will:
        1. Create transaction in database
        2. Initiate PREAUTH with IGFS (credit card gateway)
        3. Return redirect URL for customer to enter card details

        After successful PREAUTH, customer is redirected to voucher choice page.
      operationId: initiatePayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentInitiateRequest'
      responses:
        '200':
          description: Payment initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentInitiateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/payment/transaction/{transactionId}:
    get:
      summary: Get Transaction Status
      description: Retrieve current status and details of a payment transaction
      operationId: getTransactionStatus
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
          example: "abc-123-def-456"
      responses:
        '200':
          description: Transaction details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatusResponse'
        '404':
          description: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

webhooks:
  paymentCompleted:
    post:
      summary: Payment Completed Notification
      description: |
        Webhook sent to merchant's configured webhook URL when payment is completed.

        **Verification**: Check that the notification comes from PayGlobe servers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentNotification'
      responses:
        '200':
          description: Notification received
