{
  "openapi": "3.0.0",
  "paths": {
    "/v1/auth/login": {
      "post": {
        "operationId": "AuthController_login",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDto" } }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          },
          "401": {
            "description": "Generic authentication failure.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          }
        },
        "summary": "Authenticate a merchant user",
        "tags": ["Authentication"]
      }
    },
    "/v1/auth/password-recovery": {
      "post": {
        "operationId": "AuthController_requestPasswordRecovery",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/PasswordRecoveryDto" } }
          }
        },
        "responses": { "202": { "description": "" } },
        "summary": "Begin password recovery",
        "tags": ["Authentication"]
      }
    },
    "/v1/auth/password-recovery/confirmation": {
      "post": {
        "operationId": "AuthController_confirmPasswordRecovery",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PasswordRecoveryConfirmationDto" }
            }
          }
        },
        "responses": { "200": { "description": "" } },
        "summary": "Complete password recovery",
        "tags": ["Authentication"]
      }
    },
    "/v1/auth/session": {
      "get": {
        "operationId": "AuthController_session",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SessionResponseDto" }
              }
            }
          },
          "401": {
            "description": "Generic authentication failure.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          }
        },
        "security": [{ "bearer": [] }],
        "summary": "Inspect the current merchant session",
        "tags": ["Authentication"]
      }
    },
    "/v1/auth/logout": {
      "post": {
        "operationId": "AuthController_logout",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/LogoutResponseDto" } }
            }
          },
          "401": {
            "description": "Generic authentication failure.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          }
        },
        "security": [{ "bearer": [] }],
        "summary": "Revoke the current merchant session",
        "tags": ["Authentication"]
      }
    },
    "/v1/auth/session/organization": {
      "post": {
        "operationId": "AuthController_selectOrganization",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SelectOrganizationDto" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDto" } }
            }
          },
          "400": {
            "description": "",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          },
          "401": {
            "description": "Generic authentication failure.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          }
        },
        "security": [{ "bearer": [] }],
        "summary": "Select an authorized merchant organization",
        "tags": ["Authentication"]
      }
    },
    "/v1/profile": {
      "get": {
        "operationId": "MerchantOperationsController_profile",
        "parameters": [],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Retrieve the merchant profile",
        "tags": ["Merchant operations"]
      }
    },
    "/v1/stats/payments": {
      "get": {
        "operationId": "MerchantOperationsController_paymentStatistics",
        "parameters": [],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Retrieve payment statistics",
        "tags": ["Merchant operations"]
      }
    },
    "/v1/payments": {
      "post": {
        "operationId": "PaymentController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreateDto" } }
          }
        },
        "responses": { "201": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Create a payment intent",
        "tags": ["Payments"]
      },
      "get": {
        "operationId": "PaymentController_list",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" }
          },
          {
            "name": "cursor",
            "required": false,
            "in": "query",
            "schema": { "maxLength": 2048, "type": "string" }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["PENDING", "ASSIGNED", "CONFIRMED", "EXPIRED", "CANCELLED"]
            }
          },
          { "name": "currency", "required": false, "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "List payments",
        "tags": ["Payments"]
      }
    },
    "/v1/payments/{paymentId}/start": {
      "post": {
        "operationId": "PaymentController_start",
        "parameters": [
          { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } },
          {
            "name": "idempotency-key",
            "required": true,
            "in": "header",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStartDto" } }
          }
        },
        "responses": { "201": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Start a payment and acquire details",
        "tags": ["Payments"]
      }
    },
    "/v1/payments/by-external-id/{externalId}": {
      "get": {
        "operationId": "PaymentController_retrieveByExternalId",
        "parameters": [
          { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Retrieve a payment by external ID",
        "tags": ["Payments"]
      }
    },
    "/v1/payments/{paymentId}": {
      "get": {
        "operationId": "PaymentController_retrieve",
        "parameters": [
          { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Retrieve a payment",
        "tags": ["Payments"]
      }
    },
    "/v1/payments/{paymentId}/confirmation-claims": {
      "post": {
        "operationId": "PaymentController_submitClaim",
        "parameters": [
          { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } },
          {
            "name": "idempotency-key",
            "required": true,
            "in": "header",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ConfirmationClaimDto" }
            }
          }
        },
        "responses": { "201": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Submit a non-authoritative confirmation claim",
        "tags": ["Payments"]
      },
      "get": {
        "operationId": "PaymentController_listClaims",
        "parameters": [
          { "name": "paymentId", "required": true, "in": "path", "schema": { "type": "string" } },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": { "minimum": 1, "maximum": 200, "default": 50, "type": "number" }
          },
          {
            "name": "cursor",
            "required": false,
            "in": "query",
            "schema": { "maxLength": 2048, "type": "string" }
          }
        ],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "List payment confirmation claims",
        "tags": ["Payments"]
      }
    },
    "/v1/payments/{externalId}/cancel": {
      "post": {
        "operationId": "PaymentController_cancel",
        "parameters": [
          { "name": "externalId", "required": true, "in": "path", "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCancelDto" } }
          }
        },
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Cancel a payment by external ID",
        "tags": ["Payments"]
      }
    },
    "/v1/transactions": {
      "get": {
        "operationId": "FinanceController_transactions",
        "parameters": [],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "List transactions",
        "tags": ["Finance"]
      }
    },
    "/v1/transactions/{transactionId}": {
      "get": {
        "operationId": "FinanceController_transaction",
        "parameters": [
          {
            "name": "transactionId",
            "required": true,
            "in": "path",
            "schema": { "type": "string" }
          }
        ],
        "responses": { "200": { "description": "" } },
        "security": [{ "bearer": [] }, { "apiKey": [] }],
        "summary": "Retrieve a transaction",
        "tags": ["Finance"]
      }
    },
    "/v1/status": {
      "get": {
        "operationId": "StatusController_getStatus",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponseDto" } }
            }
          },
          "429": {
            "description": "",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicErrorEnvelopeDto" }
              }
            }
          }
        },
        "summary": "Retrieve public service availability",
        "tags": ["Status"]
      }
    }
  },
  "info": {
    "title": "Merchant API",
    "description": "Stateless, gateway-neutral public API for merchant integrations.",
    "version": "1.0.0",
    "contact": {}
  },
  "tags": [],
  "servers": [],
  "components": {
    "securitySchemes": {
      "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" },
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }
    },
    "schemas": {
      "LoginDto": {
        "type": "object",
        "properties": {
          "username": { "type": "string", "maxLength": 254, "example": "owner@example.test" },
          "password": {
            "type": "string",
            "maxLength": 256,
            "format": "password",
            "writeOnly": true
          }
        },
        "required": ["username", "password"]
      },
      "TokenResponseDto": {
        "type": "object",
        "properties": {
          "token": { "type": "string", "description": "Short-lived RS256 JWT bearer token." },
          "role": { "type": "string", "enum": ["MERCHANT"] },
          "requestId": { "type": "string", "format": "uuid" }
        },
        "required": ["token", "role", "requestId"]
      },
      "PublicErrorBodyDto": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "fieldErrors": {
            "type": "object",
            "additionalProperties": { "type": "array", "items": { "type": "string" } }
          },
          "retryable": { "type": "boolean" },
          "retryAfterSeconds": { "type": "number", "minimum": 0 }
        },
        "required": ["code", "message"]
      },
      "PublicErrorEnvelopeDto": {
        "type": "object",
        "properties": {
          "error": { "$ref": "#/components/schemas/PublicErrorBodyDto" },
          "requestId": { "type": "string", "format": "uuid" }
        },
        "required": ["error", "requestId"]
      },
      "PasswordRecoveryDto": {
        "type": "object",
        "properties": { "username": { "type": "string", "maxLength": 254 } },
        "required": ["username"]
      },
      "PasswordRecoveryConfirmationDto": {
        "type": "object",
        "properties": {
          "recoveryProof": { "type": "string", "minLength": 32, "maxLength": 512 },
          "newPassword": { "type": "string", "minLength": 12, "maxLength": 256 }
        },
        "required": ["recoveryProof", "newPassword"]
      },
      "SessionUserDto": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "accountState": { "type": "string" }
        },
        "required": ["id", "accountState"]
      },
      "MembershipDto": {
        "type": "object",
        "properties": {
          "merchantId": { "type": "string", "format": "uuid" },
          "status": { "type": "string" }
        },
        "required": ["merchantId", "status"]
      },
      "SessionResponseDto": {
        "type": "object",
        "properties": {
          "user": { "$ref": "#/components/schemas/SessionUserDto" },
          "organizations": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/MembershipDto" }
          },
          "selectedOrganization": { "type": "string", "format": "uuid" },
          "roles": { "type": "array", "items": { "type": "string" } },
          "permissions": { "type": "array", "items": { "type": "string" } },
          "expiresAt": { "type": "string", "format": "date-time" },
          "requestId": { "type": "string", "format": "uuid" }
        },
        "required": [
          "user",
          "organizations",
          "selectedOrganization",
          "roles",
          "permissions",
          "expiresAt",
          "requestId"
        ]
      },
      "LogoutResponseDto": {
        "type": "object",
        "properties": {
          "revoked": { "type": "boolean", "enum": [true] },
          "requestId": { "type": "string", "format": "uuid" }
        },
        "required": ["revoked", "requestId"]
      },
      "SelectOrganizationDto": {
        "type": "object",
        "properties": { "merchantId": { "type": "string", "format": "uuid" } },
        "required": ["merchantId"]
      },
      "PaymentCreateDto": {
        "type": "object",
        "properties": {
          "externalId": { "type": "string", "maxLength": 128 },
          "amount": { "type": "number", "minimum": 1, "maximum": 500000 },
          "currency": { "type": "string", "default": "RUB" },
          "webhookUrl": { "type": "string" },
          "merchantRef": { "type": "string", "maxLength": 256 },
          "ttlSeconds": { "type": "number", "minimum": 60, "maximum": 86400, "default": 1800 }
        },
        "required": ["externalId", "amount"]
      },
      "PaymentStartDto": {
        "type": "object",
        "properties": {
          "requested_detail_type": { "type": "string" },
          "integration_mode": { "type": "string", "enum": ["hosted", "p2p_details"] },
          "payment_currency": { "type": "string" }
        },
        "required": ["integration_mode"]
      },
      "ConfirmationClaimDto": {
        "type": "object",
        "properties": {
          "claimed_paid_at": { "type": "string", "format": "date-time" },
          "payer_transfer_reference": { "type": "string", "maxLength": 256 },
          "note": { "type": "string", "maxLength": 512 },
          "evidence_metadata": { "type": "object", "additionalProperties": true }
        }
      },
      "PaymentCancelDto": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "description": "Provider payment code returned by start" }
        },
        "required": ["code"]
      },
      "StatusResponseDto": {
        "type": "object",
        "properties": {
          "availability": { "type": "string", "enum": ["available"] },
          "apiVersion": { "type": "string", "enum": ["v1"] },
          "currentTime": { "type": "string", "format": "date-time" },
          "requestId": { "type": "string", "format": "uuid" }
        },
        "required": ["availability", "apiVersion", "currentTime", "requestId"]
      }
    }
  }
}