openapi: 3.1.0
info:
  title: Funtico PSP API
  description: Documentation for the API of Funtico Payment Service Provider
  version: 1.0.0
  contact:
    name: Funtico
    email: support@funtico.com
    url: https://funtico.com
servers:
  - url: https://staging.sdk.funtico.com
    description: Staging server
  - url: https://sdk.funtico.com
    description: Production server

paths:
  /api/v1/transactions:
    post:
      operationId: createTransaction
      summary: Create a transaction
      description: Create a transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionCreate"
      responses:
        "201":
          $ref: "#/components/responses/TransactionCreated"
        "400":
          $ref: "#/components/responses/InvalidBodyFormat"

  /api/v1/transactions/{id}:
    get:
      operationId: getTransactionById
      summary: Get a transaction by ID
      description: Get a transaction by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          $ref: "#/components/responses/TransactionRetrieved"
        "404":
          $ref: "#/components/responses/TransactionNotFound"

components:
  schemas:
    TransactionRead:
      type: object
      required:
        - id
        - items
        - metadata
        - success_url
        - cancel_url
        - ui_mode
        - expires_at
        - created_at
        - updated_at
        - current_status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the transaction
          example: "a433d089-38da-45c9-862e-539c377545cb"
        items:
          type: array
          items:
            $ref: "#/components/schemas/Item"
        metadata:
          $ref: "#/components/schemas/TransactionMetadata"
        success_url:
          $ref: "#/components/schemas/SuccessURL"
        cancel_url:
          $ref: "#/components/schemas/CancelURL"
        ui_mode:
          $ref: "#/components/schemas/UIMode"
        expires_at:
          type: string
          format: date-time
          description: Timestamp when the transaction will expire
          example: "2025-06-12T05:54:05.180573Z"
        created_at:
          type: string
          format: date-time
          description: Timestamp when the transaction was created
          example: "2025-06-10T07:54:05.180573Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the transaction was last updated
          example: "2025-06-10T07:54:05.180573Z"
        current_status:
          $ref: "#/components/schemas/TransactionStatus"

    TransactionCreate:
      type: object
      required:
        - items
        - ui_mode
        - expiration_sec
      properties:
        items:
          type: array
          minItems: 1
          description: Items to be purchased in the transaction. At least one item is required.
          items:
            $ref: "#/components/schemas/Item"
        metadata:
          $ref: "#/components/schemas/TransactionMetadata"
        success_url:
          $ref: "#/components/schemas/SuccessURL"
        cancel_url:
          $ref: "#/components/schemas/CancelURL"
        ui_mode:
          $ref: "#/components/schemas/UIMode"
        expiration_sec:
          type: integer
          description: Expiration time of the transaction in seconds
          example: 3600

    Currency:
      type: string
      description: Currency of the item
      example: "tico"
      enum:
        - tico
        - usd

    Item:
      type: object
      required:
        - name
        - description
        - image_url
        - metadata
        - quantity
        - unit_price
        - currency
      properties:
        name:
          type: string
          description: Name of the item
          example: "Magic Coin"
        description:
          type: [string, "null"]
          description: Description of the item
          example: "A magic coin that can be used to buy power-ups"
        image_url:
          type: [string, "null"]
          format: url
          description: URL of the item image
          example: "https://example.com/magic-coin.png"
        metadata:
          type: [object, "null"]
          description: Metadata of the item specified by the game
          example:
            xp: 100
            rarity: "common"
            category: "power-up"
        quantity:
          type: integer
          description: Quantity of the item
          example: 10
        unit_price:
          type: number
          format: float
          description: Unit price of the item
        currency:
          $ref: "#/components/schemas/Currency"

    TransactionMetadata:
      type: [object, "null"]
      description: Metadata of the transaction specified by the game
      example:
        in_game_user_id: 1234
        user_ip: "127.0.0.1"
        user_country: "US"

    SuccessURL:
      type: [string, "null"]
      format: url
      description: URL to redirect to after the transaction is successfully completed. Nullable in case of new_tab UI mode.
      example: "https://shop.game.com/success"

    CancelURL:
      type: [string, "null"]
      format: url
      description: URL to redirect to after the transaction is cancelled or failed
      example: "https://shop.game.com/cancel"

    TransactionStatus:
      type: object
      required:
        - current
        - reason
      properties:
        current:
          type: string
          description: Current status of the transaction
          example: "failed"
          enum:
            - created
            - confirmed
            - completed
            - failed
            - cancelled
            - expired
        reason:
          type: [string, "null"]
          description: Reason for the current status
          example: "Insufficient balance"

    UIMode:
      type: string
      description: UI mode of the transaction
      example: "redirect"
      enum:
        - redirect
        - new_tab

  responses:
    TransactionRetrieved:
      description: Transaction retrieved successfully
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - data
            properties:
              status:
                type: string
                enum:
                  - ok
              data:
                $ref: "#/components/schemas/TransactionRead"

    TransactionCreated:
      description: Transaction created successfully
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - data
            properties:
              status:
                type: string
                enum:
                  - transaction_created
              data:
                $ref: "#/components/schemas/TransactionRead"

    TransactionNotFound:
      description: Transaction not found
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - data
            properties:
              status:
                type: string
                enum:
                  - transaction_not_found
              data:
                type: "null"
            example:
              status: "transaction_not_found"
              data: null

    InvalidBodyFormat:
      description: Invalid body format
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - data
            properties:
              status:
                type: string
                enum:
                  - invalid_body_format
              data:
                type: "null"
            example:
              status: "invalid_body_format"
              data: null

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Client ID and Client Secret

security:
  - basicAuth: []
