{
  "openapi": "3.1.0",
  "info": {
    "title": "Northstar Payments API",
    "version": "2.4.0",
    "description": "Create and retrieve payments in the Northstar sandbox."
  },
  "servers": [
    {
      "url": "https://sandbox-api.northstar.example",
      "description": "Sandbox"
    }
  ],
  "paths": {
    "/v1/payments": {
      "post": {
        "operationId": "createPayment",
        "summary": "Create a payment",
        "description": "Creates a payment and returns its current processing state.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" },
              "example": {
                "amount": 4200,
                "currency": "USD",
                "reference": "order_1048"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Payment created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "401": { "description": "Missing or invalid credentials" }
        }
      },
      "get": {
        "operationId": "listPayments",
        "summary": "List payments",
        "responses": {
          "200": { "description": "A paginated list of payments" }
        }
      }
    },
    "/v1/payments/{paymentId}": {
      "get": {
        "operationId": "getPayment",
        "summary": "Retrieve a payment",
        "parameters": [
          {
            "name": "paymentId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Payment" }
              }
            }
          },
          "404": { "description": "Payment not found" }
        }
      }
    },
    "/v1/payments/{paymentId}/refunds": {
      "post": {
        "operationId": "refundPayment",
        "summary": "Refund a payment",
        "responses": {
          "201": { "description": "Refund created" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" }
    },
    "schemas": {
      "CreatePaymentRequest": {
        "type": "object",
        "required": ["amount", "currency"],
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 1,
            "description": "Amount in the currency's minor unit."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "reference": { "type": "string", "maxLength": 128 }
        }
      },
      "Payment": {
        "type": "object",
        "required": ["id", "amount", "currency", "status", "created_at"],
        "properties": {
          "id": { "type": "string", "example": "pay_01JQ4Z8K7VMG2" },
          "amount": { "type": "integer", "example": 4200 },
          "currency": { "type": "string", "example": "USD" },
          "status": {
            "type": "string",
            "enum": ["pending", "succeeded", "failed", "refunded"]
          },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}