openapi: 3.1.0

info:
  title: Paywaz Public API
  version: 0.1.0
  description: >
    Paywaz Public API — the developer gateway into zero-fee, crypto-native payments.
    Supports stablecoins, Solana-native settlement, and enterprise-grade webhooks.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.paywaz.com
    description: Production

tags:
  - name: Payments
    description: Create and query payments.

security:
  - ApiKeyAuth: []

paths:
  /payments:
    post:
      tags: [Payments]
      operationId: createPayment
      summary: Create a payment
      description: Create a new payment intent and return its identifier and initial status.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        $ref: "#/components/requestBodies/PaymentCreateRequest"
      responses:
        "201":
          $ref: "#/components/responses/PaymentCreated"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /payments/{paymentId}:
    get:
      tags: [Payments]
      operationId: getPayment
      summary: Get a payment
      description: Fetch a payment by its identifier.
      parameters:
        - $ref: "#/components/parameters/PaymentId"
      responses:
        "200":
          $ref: "#/components/responses/PaymentRetrieved"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Paywaz API key.

  parameters:
    PaymentId:
      name: paymentId
      in: path
      required: true
      description: The payment identifier.
      schema:
        type: string
        minLength: 1

    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >
        Optional idempotency key to safely retry requests. Reusing the same key with the
        same request body should return the same result.
      schema:
        type: string
        minLength: 1
        maxLength: 128

  headers:
    XRequestId:
      description: Unique request identifier for tracing/support.
      schema:
        type: string

  requestBodies:
    PaymentCreateRequest:
      required: true
      description: Create payment request payload.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PaymentCreateRequest"
          examples:
            basic:
              value:
                amount:
                  currency: "USD"
                  value: "49.99"

  responses:
    PaymentCreated:
      description: Payment created
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Payment"
          examples:
            created:
              value:
                id: "pay_01J0XQ8ZK6VZQ8FQ1YB9D9G9K1"
                status: "created"
                amount:
                  currency: "USD"
                  value: "49.99"
                createdAt: "2025-12-16T19:15:31Z"

    PaymentRetrieved:
      description: Payment retrieved
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Payment"
          examples:
            found:
              value:
                id: "pay_01J0XQ8ZK6VZQ8FQ1YB9D9G9K1"
                status: "created"
                amount:
                  currency: "USD"
                  value: "49.99"
                createdAt: "2025-12-16T19:15:31Z"

    BadRequest:
      description: Bad request (validation error).
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            invalid:
              value:
                error:
                  code: "invalid_request"
                  message: "Request validation failed."
                  details:
                    - field: "amount.value"
                      issue: "Must be a positive decimal string."

    Unauthorized:
      description: Authentication failed.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            missingKey:
              value:
                error:
                  code: "unauthorized"
                  message: "Missing or invalid API key."

    NotFound:
      description: Resource not found.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/XRequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            notFound:
              value:
                error:
                  code: "not_found"
                  message: "Payment not found."

  schemas:
    PaymentCreateRequest:
      type: object
      additionalProperties: false
      required: [amount]
      properties:
        amount:
          $ref: "#/components/schemas/Money"

    Payment:
      type: object
      additionalProperties: false
      required: [id, status, amount, createdAt]
      properties:
        id:
          type: string
          description: Paywaz payment identifier.
        status:
          $ref: "#/components/schemas/PaymentStatus"
        amount:
          $ref: "#/components/schemas/Money"
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp.

    PaymentStatus:
      type: string
      description: Current payment status.
      enum: [created, pending, settled, failed, canceled]

    Money:
      type: object
      additionalProperties: false
      required: [currency, value]
      properties:
        currency:
          type: string
          description: ISO 4217 currency code.
          minLength: 3
          maxLength: 3
        value:
          type: string
          description: Decimal string amount (e.g. "49.99").
          pattern: "^[0-9]+(\\.[0-9]{1,8})?$"

    ErrorResponse:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/Error"

    Error:
      type: object
      additionalProperties: false
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: array
          description: Optional field-level validation issues.
          items:
            $ref: "#/components/schemas/ErrorDetail"

    ErrorDetail:
      type: object
      additionalProperties: false
      required: [issue]
      properties:
        field:
          type: string
          description: Dot-path to the invalid field (if applicable).
        issue:
          type: string
          description: Description of the validation problem.