{
  "openapi": "3.1.0",
  "info": {
    "title": "Платежи",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.x-hub.online/api/v1"
    }
  ],
  "paths": {
    "/payments": {
      "post": {
        "operationId": "createPayment",
        "summary": "Создать платёж",
        "security": [
          {
            "apiKey": [],
            "apiSecret": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID (RFC 4122). Повтор с тем же ключом возвращает исходный ресурс."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestBody"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listPayments",
        "summary": "Список платежей",
        "security": [
          {
            "apiKey": [],
            "apiSecret": []
          }
        ]
      }
    },
    "/payments/{id}": {
      "get": {
        "operationId": "getPayment",
        "summary": "Получить платёж",
        "security": [
          {
            "apiKey": [],
            "apiSecret": []
          }
        ]
      }
    },
    "/payments/{id}/sbp-link": {
      "get": {
        "operationId": "getPaymentSbpLink",
        "summary": "СБП-ссылка платежа (голая НСПК-ссылка для своего QR)",
        "security": [
          {
            "apiKey": [],
            "apiSecret": []
          }
        ]
      }
    },
    "/payment-methods/{method_id}/exchange-rate": {
      "get": {
        "operationId": "getPaymentMethodExchangeRate",
        "summary": "Справка по способу оплаты",
        "security": [
          {
            "apiKey": [],
            "apiSecret": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      },
      "apiSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Secret"
      }
    },
    "schemas": {
      "RequestBody": {
        "type": "object",
        "properties": {
          "amount_rub": {
            "type": "string",
            "pattern": "^\\d{1,10}(\\.\\d{1,2})?$"
          },
          "external_id": {
            "type": "string",
            "maxLength": 256
          },
          "payment_method": {
            "type": "string",
            "enum": [
              "sbp",
              "card"
            ]
          },
          "method_id": {
            "type": "string",
            "format": "uuid"
          },
          "ttl_minutes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 129600,
            "description": "Срок жизни ссылки на оплату, минут (целое от 1 до 129600). Необязателен. Применяется, если способ оплаты аккаунта поддерживает свой срок; иначе ссылка живёт стандартное время этого способа. Выше максимума аккаунта — 422 VALIDATION_ERROR, платёж не создаётся. Фактический срок всегда в поле expires_at ответа."
          },
          "shop_id": {
            "type": "string",
            "format": "uuid"
          },
          "description": {
            "type": "string",
            "maxLength": 256
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {}
          },
          "client_phone": {
            "type": "string"
          },
          "client_email": {
            "type": "string",
            "format": "email",
            "maxLength": 254
          },
          "client_info": {
            "type": "object",
            "additionalProperties": {},
            "description": "Данные плательщика для антифрода X-Hub: JSON-объект до 4096 байт. Рекомендуемые ключи: ip (обязателен, если плательщик не проходит через окно оплаты X-Hub), user_agent, page_url; необязательные — accept_language, timezone. Используется только антифродом X-Hub, в банк не передаётся."
          },
          "customer_id": {
            "type": "string",
            "maxLength": 256,
            "description": "Идентификатор платящего клиента в системе мерчанта, 1–256 символов. Необязателен; используется способами оплаты, которым нужна идентификация плательщика."
          },
          "webhook_url": {
            "type": "string",
            "format": "uri"
          },
          "success_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Куда вернуть плательщика после успешной оплаты. Принимаются только адреса со схемой http или https."
          },
          "auto_return": {
            "type": "boolean",
            "description": "Автоматически вернуть плательщика в магазин после оплаты (отсчёт 5 секунд в окне оплаты). Не передано — настройка аккаунта, по умолчанию true. Действует, только если есть адрес возврата."
          },
          "payer": {
            "type": "object",
            "properties": {
              "full_name": {
                "type": "string",
                "description": "ФИО плательщика, от 2 до 150 символов."
              },
              "document_number": {
                "type": "string",
                "description": "Номер документа плательщика, от 5 до 32 букв или цифр."
              },
              "kyc_reference": {
                "type": "string",
                "description": "Идентификатор проверки клиента в системе мерчанта, до 128 символов."
              },
              "kyc_completed_at": {
                "type": "string",
                "description": "Дата и время завершения проверки клиента, ISO 8601 с часовым поясом."
              }
            },
            "required": [
              "full_name",
              "document_number"
            ],
            "additionalProperties": false,
            "description": "Данные плательщика, которые мерчант собрал при проверке своего клиента. Необязателен: нужен только способам оплаты, которые требуют данные плательщика (поле required_fields у способа оплаты); без объекта такой платёж не создаётся."
          }
        },
        "required": [
          "amount_rub",
          "payment_method"
        ],
        "additionalProperties": false
      }
    }
  }
}