{
  "openapi": "3.1.0",
  "info": {
    "title": "AvantPay API",
    "version": "3",
    "description": "Здесь описаны все методы API: платежи, способы оплаты для автоплатежей, возвраты и уведомления.",
    "contact": {
      "name": "Поддержка AvantPay",
      "email": "support@avantpay.io",
      "url": "https://avantpay.io/developers/"
    }
  },
  "externalDocs": {
    "description": "Справочник API",
    "url": "https://avantpay.io/developers/api/"
  },
  "servers": [
    {
      "url": "https://api.avantpay.io"
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "payments",
      "description": "Платежи",
      "x-displayName": "Платежи"
    },
    {
      "name": "payment_methods",
      "description": "Способы оплаты",
      "x-displayName": "Способы оплаты"
    },
    {
      "name": "refunds",
      "description": "Возвраты",
      "x-displayName": "Возвраты"
    }
  ],
  "paths": {
    "/v3/payments": {
      "post": {
        "operationId": "create_payment",
        "summary": "Создать платёж",
        "description": "Создаёт платёж и возвращает [объект платежа](https://avantpay.io/developers/api/#payment_object) со статусом `pending` и ссылкой на оплату `confirmation.confirmation_url`.\n\n> **Важно.**\n>\n> Email покупателя обязателен: передайте его в `metadata.email`. Покупатель из Telegram — `<telegram_id>@telegram.org`, например `123456789@telegram.org`.",
        "tags": [
          "payments"
        ],
        "externalDocs": {
          "description": "Справочник API: Создать платёж",
          "url": "https://avantpay.io/developers/api/#create_payment"
        },
        "parameters": [
          {
            "name": "Idempotence-Key",
            "in": "header",
            "required": true,
            "description": "Ключ идемпотентности: уникальная строка до 64 символов, лучше UUID. Новый для каждой попытки оплаты, тот же при повторе запроса. [Подробнее](https://avantpay.io/developers/api/#idempotence)",
            "schema": {
              "type": "string"
            },
            "example": "e1d2c3b4-a5f6-4789-8abc-def012345678"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentRequest"
              },
              "example": {
                "amount": {
                  "value": "1000.00",
                  "currency": "RUB"
                },
                "capture": true,
                "confirmation": {
                  "type": "redirect",
                  "return_url": "https://example.com/orders/123"
                },
                "description": "Заказ №123",
                "metadata": {
                  "email": "buyer@example.com",
                  "order_id": "123"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект платежа](https://avantpay.io/developers/api/#payment_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                },
                "examples": {
                  "200": {
                    "summary": "объект платежа со ссылкой на оплату",
                    "value": {
                      "id": "3d6f0a8e-5b2c-4e1f-9a7d-2c4b6e8f0a1b",
                      "status": "pending",
                      "paid": false,
                      "amount": {
                        "value": "1000.00",
                        "currency": "RUB"
                      },
                      "description": "Заказ №123",
                      "recipient": {
                        "account_id": "33661"
                      },
                      "created_at": "2026-10-18T10:15:30.123Z",
                      "expires_at": "2026-10-18T10:35:30.123Z",
                      "confirmation": {
                        "type": "redirect",
                        "confirmation_url": "https://avantpay.io/checkout?paymentId=3d6f0a8e-5b2c-4e1f-9a7d-2c4b6e8f0a1b",
                        "return_url": "https://example.com/orders/123"
                      },
                      "test": false,
                      "refundable": false,
                      "metadata": {
                        "email": "buyer@example.com",
                        "order_id": "123"
                      }
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "- Запрос с этим ключом ещё выполняется, у сценария `qr` — банк ещё выдаёт QR-код. Тело: `{\"type\": \"processing\", ...}`. Подождать `retry_after` миллисекунд и повторить с тем же ключом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Processing"
                },
                "example": {
                  "type": "processing",
                  "description": "Request accepted",
                  "retry_after": 2000
                }
              }
            }
          },
          "400": {
            "description": "- `invalid_request`, `parameter` — `metadata.email`: Нет `metadata`, нет ключа `email`, он пустой или это не email (больше 254 символов, неверный адрес `…@telegram.org`). Передать email покупателя. Покупатель из Telegram — `<telegram_id>@telegram.org`.\n- `invalid_request`, `parameter` — `Idempotence-Key`: Нет ключа, ключ длиннее 64 символов, переданы `Idempotence-Key` и `Idempotency-Key` с разными значениями, тот же ключ уже использован с другим телом запроса. Передать один ключ до 64 символов. Для нового платежа — новый ключ.\n- `invalid_request`, `parameter` — `capture`: Нет `capture` или это не `true`/`false` (например, строка `\"true\"`). Передать `\"capture\": true`.\n- `not_supported`, `parameter` — `capture`: `\"capture\": false`. Передать `\"capture\": true`.\n- `invalid_request`, `parameter` — `amount`, `amount.value`: Нет суммы, сумма не число, больше двух знаков после точки, не больше нуля или вне лимитов способов оплаты. Исправить сумму. Лимиты — в личном кабинете, **Ещё → Способы оплаты**.\n- `invalid_request`, `parameter` — `amount.currency`: Валюта не `RUB` или у магазина нет способов оплаты в этой валюте. Передать `\"RUB\"`.\n- `invalid_request`: У магазина не включён ни один способ оплаты. Написать в поддержку: support@avantpay.io.\n- `invalid_request`, `parameter` — `confirmation`, `confirmation.type`, `confirmation.return_url`: Нет `confirmation`, неизвестный тип, нет `return_url`, `return_url` — не адрес `http://` или `https://` либо длиннее 2048 символов, `qr` без `\"payment_method_data\": {\"type\": \"sbp\"}`. Передать `return_url`. Для `qr` — ещё способ `sbp`.\n- `not_supported`, `parameter` — `confirmation.type`: Тип, кроме `redirect` и `qr`. Передать `redirect` или `qr`.\n- `invalid_request`, `parameter` — `payment_method_data.type`: Такого способа нет у магазина, он не работает в рублях, или включено несколько способов этого типа. Передать `sbp` или `bank_card`, идентификатор способа из `description` либо не передавать `payment_method_data`.\n- `invalid_request`, `parameter` — `description`: Длиннее 128 символов. Сократить описание.\n- `invalid_request`, `parameter` — `client_ip`: Сценарий `qr`, а `client_ip` — не IPv4 и не IPv6. У `redirect` неверный адрес ошибки не даёт, но и не сохраняется. Передать IP покупателя или не передавать поле.\n- `invalid_request`, `parameter` — `metadata`: `metadata` — не объект, больше 16 ключей, длинное имя ключа или значение, значение — массив или объект. Привести к правилам из раздела [metadata](https://avantpay.io/developers/api/#format-metadata).\n- `invalid_request`, `parameter` — `metadata.<ключ>`: Для магазина по договору с AvantPay обязательны ещё некоторые ключи `metadata`, а их нет. Передать ключ, названный в `parameter`.\n- `invalid_request`, `parameter` — `order_id`, `webhook_url`, `expires_at`, `avantpay`: Передано поле, которого в запросе нет. Номер заказа передать в `metadata.order_id`. Адрес уведомлений указать в личном кабинете. Срок оплаты не передавать: он 20 минут.\n- `not_supported`, `parameter` — имя поля: Передано поле, которого нет в API: `receipt`, `payment_method_data.card` и другие. Убрать поле из запроса.\n- `invalid_request`: Тело запроса — не JSON. Передать правильный JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "400": {
                    "summary": "неверный email покупателя",
                    "value": {
                      "type": "error",
                      "id": "2b7d4e9a-1c3f-4a5b-8d6e-7f0a1b2c3d4e",
                      "code": "invalid_request",
                      "description": "metadata.email must be the buyer's email address (up to 254 characters), for a Telegram buyer use <id or username>@telegram.org",
                      "parameter": "metadata.email"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`, `parameter` — `Authorization`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: У ключа нет права «Платежи» или магазин не активен. Написать в поддержку: support@avantpay.io.\n- `forbidden`, `parameter` — `confirmation.type`: Сценарий (обычно `qr`) не включён для магазина. Использовать `redirect` или написать в поддержку.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "- `invalid_request`: Тело запроса больше 5 МБ. Уменьшить тело.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "415": {
            "description": "- `invalid_request`: Нет заголовка `Content-Type: application/json`. Передать заголовок.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Подождать `retry_after` миллисекунд и повторить с тем же ключом.\n- `too_many_requests`: В эту же секунду создаются другие платежи этого покупателя. Платёж не создан. Подождать `retry_after` миллисекунд и повторить с тем же ключом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Платёж мог создаться. Повторить с тем же ключом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_payments_list",
        "summary": "Список платежей",
        "description": "Возвращает платежи вашего магазина от новых к старым. Можно отфильтровать по дате, статусу и способу оплаты. Список отдаётся страницами. Заголовок `Idempotence-Key` этому методу не нужен. Тела у запроса нет.",
        "tags": [
          "payments"
        ],
        "externalDocs": {
          "description": "Справочник API: Список платежей",
          "url": "https://avantpay.io/developers/api/#get_payments_list"
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Сколько платежей на странице: от 1 до 100. По умолчанию 10.",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Значение `next_cursor` из предыдущего ответа — чтобы получить следующую страницу. Передавайте как есть.",
            "schema": {
              "type": "string"
            },
            "example": "MjAyNi0xMC0xN1QxODozOTo1NS44NzFa"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Только платежи с этим статусом: `pending`, `succeeded` или `canceled`.",
            "schema": {
              "type": "string"
            },
            "example": "succeeded"
          },
          {
            "name": "payment_method",
            "in": "query",
            "required": false,
            "description": "Только платежи этим способом: `sbp` или `bank_card`.",
            "schema": {
              "type": "string"
            },
            "example": "sbp"
          },
          {
            "name": "created_at.gte",
            "in": "query",
            "required": false,
            "description": "Созданы в этот момент или позже. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "created_at.gt",
            "in": "query",
            "required": false,
            "description": "Созданы позже этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "created_at.lte",
            "in": "query",
            "required": false,
            "description": "Созданы в этот момент или раньше. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-31T23:59:59.999Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-31T23:59:59.999Z"
          },
          {
            "name": "created_at.lt",
            "in": "query",
            "required": false,
            "description": "Созданы раньше этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-11-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-11-01T00:00:00.000Z"
          },
          {
            "name": "captured_at.gte",
            "in": "query",
            "required": false,
            "description": "Оплачены в этот момент или позже. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "captured_at.gt",
            "in": "query",
            "required": false,
            "description": "Оплачены позже этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "captured_at.lte",
            "in": "query",
            "required": false,
            "description": "Оплачены в этот момент или раньше. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-31T23:59:59.999Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-31T23:59:59.999Z"
          },
          {
            "name": "captured_at.lt",
            "in": "query",
            "required": false,
            "description": "Оплачены раньше этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-11-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-11-01T00:00:00.000Z"
          }
        ],
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт объект списка: платежи в `items` — [объекты платежа](https://avantpay.io/developers/api/#payment_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetPaymentsListResponse"
                },
                "examples": {
                  "200": {
                    "summary": "объект списка, первая страница",
                    "value": {
                      "type": "list",
                      "items": [
                        {
                          "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                          "status": "succeeded",
                          "paid": true,
                          "amount": {
                            "value": "1000.00",
                            "currency": "RUB"
                          },
                          "income_amount": {
                            "value": "975.00",
                            "currency": "RUB"
                          },
                          "description": "Заказ №123",
                          "recipient": {
                            "account_id": "33661",
                            "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
                          },
                          "payment_method": {
                            "type": "bank_card",
                            "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                            "saved": false,
                            "status": "inactive",
                            "title": "Банковская карта"
                          },
                          "captured_at": "2026-10-18T10:17:02.418Z",
                          "created_at": "2026-10-18T10:15:30.123Z",
                          "expires_at": "2026-10-18T10:35:30.123Z",
                          "confirmation": {
                            "type": "redirect",
                            "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                            "return_url": "https://example.com/orders/123"
                          },
                          "test": false,
                          "refundable": true,
                          "metadata": {
                            "email": "buyer@example.com",
                            "order_id": "123"
                          }
                        },
                        {
                          "id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
                          "status": "succeeded",
                          "paid": true,
                          "amount": {
                            "value": "250.00",
                            "currency": "RUB"
                          },
                          "income_amount": {
                            "value": "243.75",
                            "currency": "RUB"
                          },
                          "description": "Заказ №122",
                          "recipient": {
                            "account_id": "33661",
                            "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
                          },
                          "payment_method": {
                            "type": "sbp",
                            "id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
                            "saved": false,
                            "status": "inactive",
                            "title": "СБП"
                          },
                          "captured_at": "2026-10-17T18:41:09.004Z",
                          "created_at": "2026-10-17T18:39:55.871Z",
                          "expires_at": "2026-10-17T18:59:55.871Z",
                          "confirmation": {
                            "type": "redirect",
                            "confirmation_url": "https://avantpay.io/checkout?paymentId=c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
                            "return_url": "https://example.com/orders/122"
                          },
                          "test": false,
                          "refunded_amount": {
                            "value": "50.00",
                            "currency": "RUB"
                          },
                          "refundable": true,
                          "metadata": {
                            "email": "buyer@example.com",
                            "order_id": "122"
                          }
                        }
                      ],
                      "next_cursor": "MjAyNi0xMC0xN1QxODozOTo1NS44NzFafGM0YThlMmYxLTliM2QtNGY2YS04ZTFjLTdkMmI1YTlmM2U2MA"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `invalid_request`: `limit` — не целое число от 1 до 100, `cursor` — не из `next_cursor`, дата не в формате ISO 8601, `status` — незнакомое значение, параметр передан дважды. Имя параметра — в `parameter`. Исправить параметр.\n- `not_supported`: Передан `order_id`. `parameter` — `order_id`. Убрать параметр. Получать платёж по `id` из заказа.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "400": {
                    "summary": "фильтр по номеру заказа не поддерживается",
                    "value": {
                      "type": "error",
                      "id": "4c2e8a1f-6b3d-4f5a-9e7c-0b1d2e3f4a5b",
                      "code": "not_supported",
                      "description": "order_id is not supported: save the payment id in your order and get the payment with GET /v3/payments/{payment_id}",
                      "parameter": "order_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v3/payments/{payment_id}": {
      "get": {
        "operationId": "get_payment",
        "summary": "Получить платёж",
        "description": "Возвращает [объект платежа](https://avantpay.io/developers/api/#payment_object) в текущем состоянии.",
        "tags": [
          "payments"
        ],
        "externalDocs": {
          "description": "Справочник API: Получить платёж",
          "url": "https://avantpay.io/developers/api/#get_payment"
        },
        "parameters": [
          {
            "name": "payment_id",
            "in": "path",
            "required": true,
            "description": "`id` платежа из ответа на его создание.",
            "schema": {
              "type": "string"
            },
            "example": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f"
          }
        ],
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект платежа](https://avantpay.io/developers/api/#payment_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Payment"
                },
                "examples": {
                  "200": {
                    "summary": "объект платежа, оплаченного картой",
                    "value": {
                      "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                      "status": "succeeded",
                      "paid": true,
                      "amount": {
                        "value": "1000.00",
                        "currency": "RUB"
                      },
                      "income_amount": {
                        "value": "975.00",
                        "currency": "RUB"
                      },
                      "description": "Заказ №123",
                      "recipient": {
                        "account_id": "33661",
                        "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
                      },
                      "payment_method": {
                        "type": "bank_card",
                        "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                        "saved": false,
                        "status": "inactive",
                        "title": "Банковская карта"
                      },
                      "captured_at": "2026-10-18T10:17:02.418Z",
                      "created_at": "2026-10-18T10:15:30.123Z",
                      "expires_at": "2026-10-18T10:35:30.123Z",
                      "confirmation": {
                        "type": "redirect",
                        "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                        "return_url": "https://example.com/orders/123"
                      },
                      "test": false,
                      "refundable": true,
                      "metadata": {
                        "email": "buyer@example.com",
                        "order_id": "123"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "- `not_found`: Платежа с таким `id` нет у вашего магазина. Платёж другого магазина тоже даёт 404. `parameter` — `payment_id`. Проверить `id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v3/payment_methods": {
      "post": {
        "operationId": "create_payment_method",
        "summary": "Создать способ оплаты",
        "description": "Создаёт способ оплаты — банковскую карту — без платежа и возвращает [объект способа оплаты](https://avantpay.io/developers/api/#payment_method_object) в статусе `pending` со ссылкой `confirmation.confirmation_url`. Перенаправьте покупателя по ссылке: он подтвердит карту, на ней заблокируется и сразу вернётся 1 ₽. Когда карта сохранится, статус станет `active` и придёт уведомление `payment_method.active`. Ссылка действует 1 час.\n\n> **Важно.**\n>\n> Автоплатежи и сохранение карты без платежа включает поддержка AvantPay по письму на support@avantpay.io. Без этого API ответит 403 `forbidden`.",
        "tags": [
          "payment_methods"
        ],
        "externalDocs": {
          "description": "Справочник API: Создать способ оплаты",
          "url": "https://avantpay.io/developers/api/#create_payment_method"
        },
        "parameters": [
          {
            "name": "Idempotence-Key",
            "in": "header",
            "required": true,
            "description": "Ключ идемпотентности: уникальная строка до 64 символов. [Подробнее](https://avantpay.io/developers/api/#idempotence)",
            "schema": {
              "type": "string"
            },
            "example": "3c6e9a1f-2b4d-4f8a-9c7e-5d1b3a2f4e6c"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentMethodRequest"
              },
              "example": {
                "type": "bank_card",
                "confirmation": {
                  "type": "redirect",
                  "return_url": "https://example.com/account/cards"
                },
                "metadata": {
                  "customer_id": "1042"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект способа оплаты](https://avantpay.io/developers/api/#payment_method_object) в статусе `pending`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethod"
                },
                "examples": {
                  "200": {
                    "summary": "способ оплаты ждёт подтверждения покупателем",
                    "value": {
                      "type": "bank_card",
                      "id": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
                      "saved": false,
                      "status": "pending",
                      "holder": {
                        "account_id": "33661"
                      },
                      "metadata": {
                        "customer_id": "1042"
                      },
                      "confirmation": {
                        "type": "redirect",
                        "confirmation_url": "https://avantpay.io/checkout/bind?paymentMethodId=9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
                        "return_url": "https://example.com/account/cards"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `invalid_request`, `parameter` — `Idempotence-Key`: Нет ключа, ключ длиннее 64 символов или уже использован с другим телом запроса. Передать новый ключ до 64 символов.\n- `invalid_request`, `parameter` — `type`: Нет `type`, значение не `bank_card` или у магазина нет карты, которую можно сохранить. Передать `bank_card`. Если ошибка повторяется — написать в поддержку: support@avantpay.io.\n- `not_supported`, `parameter` — `type`: `type` равен `sbp`. Сохранить СБП платежом с `save_payment_method: true`.\n- `not_supported`, `parameter` — `card`: Переданы данные карты. Убрать `card`: покупатель вводит карту на странице по `confirmation_url`.\n- `invalid_request`, `parameter` — `confirmation`, `confirmation.type`, `confirmation.return_url`: Нет `confirmation`, `type` не `redirect` или `return_url` — не адрес `http://` или `https://`. Передать `confirmation` с `type` `redirect` и адресом возврата.\n- `invalid_request`, `parameter` — `metadata`: `metadata` — не объект, больше 16 ключей, длинное имя ключа или значение. Привести к правилам из раздела [metadata](https://avantpay.io/developers/api/#format-metadata).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "400": {
                    "summary": "сохранить СБП без платежа нельзя",
                    "value": {
                      "type": "error",
                      "id": "4b2d6f8a-1c3e-4a5b-9d7f-0e2a4c6b8d1f",
                      "code": "not_supported",
                      "description": "type sbp is not supported for saving without a payment: create a payment with save_payment_method: true",
                      "parameter": "type"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`, `parameter` — `Authorization`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Автоплатежи или сохранение карты без платежа не включены, у ключа нет права «Платежи» или магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд с тем же ключом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить с тем же ключом и тем же телом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v3/payment_methods/{payment_method_id}": {
      "get": {
        "operationId": "get_payment_method",
        "summary": "Получить способ оплаты",
        "description": "Возвращает [объект способа оплаты](https://avantpay.io/developers/api/#payment_method_object) в текущем состоянии.",
        "tags": [
          "payment_methods"
        ],
        "externalDocs": {
          "description": "Справочник API: Получить способ оплаты",
          "url": "https://avantpay.io/developers/api/#get_payment_method"
        },
        "parameters": [
          {
            "name": "payment_method_id",
            "in": "path",
            "required": true,
            "description": "ID способа оплаты: `payment_method.id` из платежа или `id` из ответа на создание способа.",
            "schema": {
              "type": "string"
            },
            "example": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
          }
        ],
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект способа оплаты](https://avantpay.io/developers/api/#payment_method_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentMethod"
                },
                "examples": {
                  "200": {
                    "summary": "карта сохранена",
                    "value": {
                      "type": "bank_card",
                      "id": "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d",
                      "saved": true,
                      "status": "active",
                      "title": "Bank card *4444",
                      "card": {
                        "first6": "220220",
                        "last4": "4444",
                        "expiry_month": "07",
                        "expiry_year": "2030",
                        "card_type": "Mir",
                        "issuer_country": "RU",
                        "issuer_name": "Sberbank"
                      },
                      "holder": {
                        "account_id": "33661"
                      },
                      "metadata": {
                        "customer_id": "1042"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "- `not_found`: Способа оплаты с таким `id` нет у вашего магазина. `parameter` — `payment_method_id`. Проверить `id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "404": {
                    "summary": "способа оплаты нет у магазина",
                    "value": {
                      "type": "error",
                      "id": "7e3a5c1b-9d2f-4b6a-8c4e-2f1d3b5a7c9e",
                      "code": "not_found",
                      "description": "Payment method with the specified id was not found",
                      "parameter": "payment_method_id"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v3/refunds": {
      "post": {
        "operationId": "create_refund",
        "summary": "Создать возврат",
        "description": "Создаёт возврат по оплаченному платежу и возвращает [объект возврата](https://avantpay.io/developers/api/#refund_object). У нового возврата статус `pending`. Можно вернуть всю сумму платежа или часть. Деньги вернутся покупателю тем же способом, которым он платил.\n\n> **Важно.**\n>\n> Для возвратов у ключа должно быть включено право «Возвраты». По умолчанию оно выключено: его включает поддержка AvantPay по письму на support@avantpay.io. Без права API ответит 403 `forbidden`.",
        "tags": [
          "refunds"
        ],
        "externalDocs": {
          "description": "Справочник API: Создать возврат",
          "url": "https://avantpay.io/developers/api/#create_refund"
        },
        "parameters": [
          {
            "name": "Idempotence-Key",
            "in": "header",
            "required": true,
            "description": "Ключ идемпотентности: уникальная строка до 64 символов. Один ключ — один возврат: новый для каждого возврата, тот же при повторе запроса. [Подробнее](https://avantpay.io/developers/api/#idempotence)",
            "schema": {
              "type": "string"
            },
            "example": "refund-123-1"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRefundRequest"
              },
              "example": {
                "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                "amount": {
                  "value": "300.00",
                  "currency": "RUB"
                },
                "description": "Возврат по заказу №123",
                "metadata": {
                  "order_id": "123"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект возврата](https://avantpay.io/developers/api/#refund_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refund"
                },
                "examples": {
                  "200": {
                    "summary": "новый возврат в статусе pending",
                    "value": {
                      "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
                      "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                      "status": "pending",
                      "created_at": "2026-10-19T09:40:12.305Z",
                      "amount": {
                        "value": "300.00",
                        "currency": "RUB"
                      },
                      "description": "Возврат по заказу №123",
                      "metadata": {
                        "order_id": "123"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `invalid_request`, `parameter` — `Idempotence-Key`: Нет ключа, ключ длиннее 64 символов или переданы `Idempotence-Key` и `Idempotency-Key` с разными значениями. Передать один ключ до 64 символов.\n- `invalid_request`, `parameter` — `Idempotence-Key`: Ключ уже использован с другим телом запроса. Значит, возврат с этим ключом уже создан. Не создавать новый возврат, пока не найдёте этот в [списке возвратов](https://avantpay.io/developers/api/#get_refunds_list) по `payment_id`. Новый ключ — только если вы по ошибке взяли этот ключ для другого возврата.\n- `invalid_request`, `parameter` — `payment_id`: Нет `payment_id` или в нём не 36 символов. Передать `id` платежа.\n- `invalid_request`, `parameter` — `payment_id`: Платёж не оплачен: его статус `pending` или `canceled`. Вернуть можно только платёж в статусе `succeeded`.\n- `invalid_request`, `parameter` — `payment_id`: По платежу уже выполняется возврат. Дождаться, когда он станет `succeeded` или `canceled`, и создать следующий возврат с новым ключом.\n- `invalid_request`, `parameter` — `payment_id`: Платёж уже возвращён полностью. Ничего: возвращать больше нечего.\n- `invalid_request`, `parameter` — `payment_id`: По платежу уже 10 возвратов. Написать в поддержку: support@avantpay.io.\n- `invalid_request`, `parameter` — `payment_id`: Платёж нельзя вернуть через API: способ оплаты не поддерживает возвраты, платёж проверяет AvantPay или он не зачислен на счёт магазина. Написать в поддержку: support@avantpay.io.\n- `invalid_request`, `parameter` — `amount`, `amount.value`: Нет суммы, сумма не число, больше двух знаков после точки, не больше нуля, больше остатка платежа (остаток — в `description`) или меньше 1 ₽, но не весь остаток. Исправить сумму.\n- `invalid_request`, `parameter` — `amount.currency`: Нет валюты, это не код валюты или она не совпадает с валютой платежа. Передать `\"RUB\"`.\n- `invalid_request`, `parameter` — `description`: Длиннее 250 символов или не строка. Сократить комментарий.\n- `invalid_request`, `parameter` — `metadata`: `metadata` — не объект, больше 16 ключей, длинное имя ключа или значение, значение — массив или объект. Привести к правилам из раздела [metadata](https://avantpay.io/developers/api/#format-metadata).\n- `not_supported`, `parameter` — имя поля: Передано поле `receipt`, `sources`, `deal` или `refund_method_data` с непустым значением. Убрать поле: деньги возвращаются тем же способом оплаты, чеки AvantPay не отправляет.\n- `invalid_request`: Тело запроса — не JSON. Передать правильный JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "400": {
                    "summary": "по платежу уже выполняется возврат",
                    "value": {
                      "type": "error",
                      "id": "8f2a6d1c-3e5b-4c7a-9d0e-1b2c3d4e5f60",
                      "code": "invalid_request",
                      "description": "Another refund of this payment is in progress: wait until it is succeeded or canceled, then retry with a new Idempotence-Key",
                      "parameter": "payment_id"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`, `parameter` — `Authorization`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: У ключа нет права «Возвраты». Написать в поддержку: support@avantpay.io.\n- `forbidden`: Возвраты разрешены только с IP-адресов из списка ключа, а запрос пришёл с другого. Отправлять запрос с сервера, IP-адрес которого есть в списке, или попросить поддержку добавить адрес.\n- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                },
                "examples": {
                  "403": {
                    "summary": "у ключа не включено право «Возвраты»",
                    "value": {
                      "type": "error",
                      "id": "3c7e1a9b-5d2f-4b8e-a6c4-9e0f1d2c3b4a",
                      "code": "forbidden",
                      "description": "Refunds via the API are disabled for this API key: contact AvantPay support"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "- `not_found`, `parameter` — `payment_id`: Платежа с таким `id` нет у вашего магазина. Проверить `id` платежа.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "- `invalid_request`: Тело запроса больше 5 МБ. Уменьшить тело.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "415": {
            "description": "- `invalid_request`: Нет заголовка `Content-Type: application/json`. Передать заголовок.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду или у магазина уже 20 возвратов в статусе `pending`. Подождать `retry_after` миллисекунд и повторить с тем же ключом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Возврат мог создаться. Повторить с тем же ключом и тем же телом.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "get_refunds_list",
        "summary": "Список возвратов",
        "description": "Возвращает возвраты вашего магазина от новых к старым: и созданные через API, и сделанные в личном кабинете. Можно отфильтровать по платежу, статусу и дате создания. Список отдаётся страницами. Заголовок `Idempotence-Key` этому методу не нужен. Тела у запроса нет.",
        "tags": [
          "refunds"
        ],
        "externalDocs": {
          "description": "Справочник API: Список возвратов",
          "url": "https://avantpay.io/developers/api/#get_refunds_list"
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Сколько возвратов на странице: от 1 до 100. По умолчанию 10.",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Значение `next_cursor` из предыдущего ответа — чтобы получить следующую страницу. Передавайте как есть.",
            "schema": {
              "type": "string"
            },
            "example": "MjAyNi0xMC0xN1QxODozOTo1NS44NzFa"
          },
          {
            "name": "payment_id",
            "in": "query",
            "required": false,
            "description": "Только возвраты этого платежа: его `id`.",
            "schema": {
              "type": "string"
            },
            "example": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Только возвраты с этим статусом: `pending`, `succeeded` или `canceled`.",
            "schema": {
              "type": "string"
            },
            "example": "succeeded"
          },
          {
            "name": "created_at.gte",
            "in": "query",
            "required": false,
            "description": "Созданы в этот момент или позже. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "created_at.gt",
            "in": "query",
            "required": false,
            "description": "Созданы позже этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "created_at.lte",
            "in": "query",
            "required": false,
            "description": "Созданы в этот момент или раньше. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-31T23:59:59.999Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-31T23:59:59.999Z"
          },
          {
            "name": "created_at.lt",
            "in": "query",
            "required": false,
            "description": "Созданы раньше этого момента. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-11-01T00:00:00.000Z`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-11-01T00:00:00.000Z"
          }
        ],
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт объект списка: возвраты в `items` — [объекты возврата](https://avantpay.io/developers/api/#refund_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetRefundsListResponse"
                },
                "examples": {
                  "200": {
                    "summary": "объект списка, последняя страница",
                    "value": {
                      "type": "list",
                      "items": [
                        {
                          "id": "a3c9e7b1-2d4f-4e6a-9b8c-1f0e2d3c4b5a",
                          "payment_id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
                          "status": "canceled",
                          "cancellation_details": {
                            "party": "avantpay",
                            "reason": "insufficient_funds"
                          },
                          "created_at": "2026-10-18T08:12:44.019Z",
                          "amount": {
                            "value": "100.00",
                            "currency": "RUB"
                          },
                          "metadata": {}
                        },
                        {
                          "id": "9d4b2e6f-1a3c-4d5e-8f7a-6b5c4d3e2f10",
                          "payment_id": "c4a8e2f1-9b3d-4f6a-8e1c-7d2b5a9f3e60",
                          "status": "succeeded",
                          "created_at": "2026-10-17T19:05:31.642Z",
                          "amount": {
                            "value": "50.00",
                            "currency": "RUB"
                          },
                          "description": "Возврат по заказу №122",
                          "metadata": {
                            "order_id": "122"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "- `invalid_request`: `limit` — не целое число от 1 до 100, `cursor` — не из `next_cursor`, дата не в формате ISO 8601, `status` — незнакомое значение, параметр передан дважды. Имя параметра — в `parameter`. Исправить параметр.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v3/refunds/{refund_id}": {
      "get": {
        "operationId": "get_refund",
        "summary": "Получить возврат",
        "description": "Возвращает [объект возврата](https://avantpay.io/developers/api/#refund_object) в текущем состоянии.",
        "tags": [
          "refunds"
        ],
        "externalDocs": {
          "description": "Справочник API: Получить возврат",
          "url": "https://avantpay.io/developers/api/#get_refund"
        },
        "parameters": [
          {
            "name": "refund_id",
            "in": "path",
            "required": true,
            "description": "`id` возврата из ответа на его создание или из списка возвратов.",
            "schema": {
              "type": "string"
            },
            "example": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87"
          }
        ],
        "responses": {
          "200": {
            "description": "В ответ на запрос придёт [объект возврата](https://avantpay.io/developers/api/#refund_object) в актуальном статусе.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refund"
                },
                "examples": {
                  "200": {
                    "summary": "объект возврата, деньги вернули покупателю",
                    "value": {
                      "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
                      "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                      "status": "succeeded",
                      "created_at": "2026-10-19T09:40:12.305Z",
                      "amount": {
                        "value": "300.00",
                        "currency": "RUB"
                      },
                      "description": "Возврат по заказу №123",
                      "metadata": {
                        "order_id": "123"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "- `invalid_credentials`: Неверный ID магазина или ключ. Проверить ключи.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "- `forbidden`: Магазин не активен. Написать в поддержку: support@avantpay.io.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "404": {
            "description": "- `not_found`: Возврата с таким `id` нет у вашего магазина. Возврат другого магазина тоже даёт 404. `parameter` — `refund_id`. Проверить `id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "- `too_many_requests`: Больше 50 запросов в секунду. Повторить через `retry_after` миллисекунд.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "500": {
            "description": "- `internal_server_error`: Сбой у AvantPay. Повторить запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "default": {
            "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "payment.succeeded": {
      "post": {
        "operationId": "webhook_payment_succeeded",
        "summary": "payment.succeeded",
        "description": "Платёж оплачен.\n\nУведомление — POST-запрос от AvantPay на ваш сервер о событии ([Уведомления](https://avantpay.io/developers/webhooks/)).",
        "externalDocs": {
          "description": "Справочник API: Объект уведомления",
          "url": "https://avantpay.io/developers/api/#notification_object"
        },
        "parameters": [
          {
            "name": "Signature-Timestamp",
            "in": "header",
            "required": false,
            "description": "Время отправки, Unix-время в секундах.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Signature",
            "in": "header",
            "required": false,
            "description": "Подпись: `v1=` и HMAC-SHA256 строки `<Signature-Timestamp>.<тело запроса>` секретным ключом API в шестнадцатеричном виде. Как проверить — в разделе [Подпись](https://avantpay.io/developers/webhooks/#signature).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Notification"
                  }
                ],
                "properties": {
                  "event": {
                    "const": "payment.succeeded"
                  },
                  "object": {
                    "$ref": "#/components/schemas/Payment"
                  }
                }
              },
              "examples": {
                "quick-start": {
                  "value": {
                    "type": "notification",
                    "event": "payment.succeeded",
                    "object": {
                      "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                      "status": "succeeded",
                      "paid": true,
                      "amount": {
                        "value": "100.00",
                        "currency": "RUB"
                      },
                      "income_amount": {
                        "value": "97.50",
                        "currency": "RUB"
                      },
                      "description": "Заказ №1",
                      "recipient": {
                        "account_id": "33661",
                        "gateway_id": "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
                      },
                      "payment_method": {
                        "type": "bank_card",
                        "id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                        "saved": false,
                        "status": "inactive",
                        "title": "Банковская карта"
                      },
                      "captured_at": "2026-10-18T10:17:02.418Z",
                      "created_at": "2026-10-18T10:15:30.123Z",
                      "expires_at": "2026-10-18T10:35:30.123Z",
                      "confirmation": {
                        "type": "redirect",
                        "confirmation_url": "https://avantpay.io/checkout?paymentId=2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                        "return_url": "https://example.com/orders/1"
                      },
                      "test": false,
                      "refundable": true,
                      "metadata": {
                        "email": "buyer@example.com",
                        "order_id": "1"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ответьте кодом 200 не позже чем через 10 секунд. Иначе AvantPay повторит уведомление ([расписание повторов](https://avantpay.io/developers/webhooks/#retries))."
          }
        },
        "security": []
      }
    },
    "payment.canceled": {
      "post": {
        "operationId": "webhook_payment_canceled",
        "summary": "payment.canceled",
        "description": "Платёж отменён: истёк срок оплаты, банк отказал или сработала проверка.\n\nУведомление — POST-запрос от AvantPay на ваш сервер о событии ([Уведомления](https://avantpay.io/developers/webhooks/)).",
        "externalDocs": {
          "description": "Справочник API: Объект уведомления",
          "url": "https://avantpay.io/developers/api/#notification_object"
        },
        "parameters": [
          {
            "name": "Signature-Timestamp",
            "in": "header",
            "required": false,
            "description": "Время отправки, Unix-время в секундах.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Signature",
            "in": "header",
            "required": false,
            "description": "Подпись: `v1=` и HMAC-SHA256 строки `<Signature-Timestamp>.<тело запроса>` секретным ключом API в шестнадцатеричном виде. Как проверить — в разделе [Подпись](https://avantpay.io/developers/webhooks/#signature).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Notification"
                  }
                ],
                "properties": {
                  "event": {
                    "const": "payment.canceled"
                  },
                  "object": {
                    "$ref": "#/components/schemas/Payment"
                  }
                }
              },
              "examples": {
                "api": {
                  "value": {
                    "type": "notification",
                    "event": "payment.canceled",
                    "object": {
                      "id": "8d0e4b52-7c19-4a6e-b3f1-5e2a9c7d1b40",
                      "status": "canceled",
                      "paid": false,
                      "amount": {
                        "value": "500.00",
                        "currency": "RUB"
                      },
                      "description": "Заказ №125",
                      "recipient": {
                        "account_id": "33661"
                      },
                      "created_at": "2026-10-18T12:00:00.000Z",
                      "expires_at": "2026-10-18T12:20:00.000Z",
                      "confirmation": {
                        "type": "redirect",
                        "confirmation_url": "https://avantpay.io/checkout?paymentId=8d0e4b52-7c19-4a6e-b3f1-5e2a9c7d1b40",
                        "return_url": "https://example.com/orders/125"
                      },
                      "test": false,
                      "refundable": false,
                      "metadata": {
                        "email": "buyer@example.com",
                        "order_id": "125"
                      },
                      "cancellation_details": {
                        "party": "avantpay",
                        "reason": "expired_on_confirmation"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ответьте кодом 200 не позже чем через 10 секунд. Иначе AvantPay повторит уведомление ([расписание повторов](https://avantpay.io/developers/webhooks/#retries))."
          }
        },
        "security": []
      }
    },
    "refund.succeeded": {
      "post": {
        "operationId": "webhook_refund_succeeded",
        "summary": "refund.succeeded",
        "description": "Возврат выполнен — полный или частичный, созданный через API или в личном кабинете.\n\nУведомление — POST-запрос от AvantPay на ваш сервер о событии ([Уведомления](https://avantpay.io/developers/webhooks/)).",
        "externalDocs": {
          "description": "Справочник API: Объект уведомления",
          "url": "https://avantpay.io/developers/api/#notification_object"
        },
        "parameters": [
          {
            "name": "Signature-Timestamp",
            "in": "header",
            "required": false,
            "description": "Время отправки, Unix-время в секундах.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Signature",
            "in": "header",
            "required": false,
            "description": "Подпись: `v1=` и HMAC-SHA256 строки `<Signature-Timestamp>.<тело запроса>` секретным ключом API в шестнадцатеричном виде. Как проверить — в разделе [Подпись](https://avantpay.io/developers/webhooks/#signature).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Notification"
                  }
                ],
                "properties": {
                  "event": {
                    "const": "refund.succeeded"
                  },
                  "object": {
                    "$ref": "#/components/schemas/Refund"
                  }
                }
              },
              "examples": {
                "api": {
                  "value": {
                    "type": "notification",
                    "event": "refund.succeeded",
                    "object": {
                      "id": "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87",
                      "payment_id": "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f",
                      "status": "succeeded",
                      "created_at": "2026-10-19T09:40:12.305Z",
                      "amount": {
                        "value": "300.00",
                        "currency": "RUB"
                      },
                      "description": "Возврат по заказу №123",
                      "metadata": {
                        "order_id": "123"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ответьте кодом 200 не позже чем через 10 секунд. Иначе AvantPay повторит уведомление ([расписание повторов](https://avantpay.io/developers/webhooks/#retries))."
          }
        },
        "security": []
      }
    },
    "payment_method.active": {
      "post": {
        "operationId": "webhook_payment_method_active",
        "summary": "payment_method.active",
        "description": "Способ оплаты сохранён для автоплатежей.\n\nУведомление — POST-запрос от AvantPay на ваш сервер о событии ([Уведомления](https://avantpay.io/developers/webhooks/)).",
        "externalDocs": {
          "description": "Справочник API: Объект уведомления",
          "url": "https://avantpay.io/developers/api/#notification_object"
        },
        "parameters": [
          {
            "name": "Signature-Timestamp",
            "in": "header",
            "required": false,
            "description": "Время отправки, Unix-время в секундах.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Signature",
            "in": "header",
            "required": false,
            "description": "Подпись: `v1=` и HMAC-SHA256 строки `<Signature-Timestamp>.<тело запроса>` секретным ключом API в шестнадцатеричном виде. Как проверить — в разделе [Подпись](https://avantpay.io/developers/webhooks/#signature).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Notification"
                  }
                ],
                "properties": {
                  "event": {
                    "const": "payment_method.active"
                  },
                  "object": {
                    "$ref": "#/components/schemas/PaymentMethod"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ответьте кодом 200 не позже чем через 10 секунд. Иначе AvantPay повторит уведомление ([расписание повторов](https://avantpay.io/developers/webhooks/#retries))."
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Адрес API — `https://api.avantpay.io/v3`. Пути методов добавляются к нему: `https://api.avantpay.io/v3/payments`. Запросы — только по HTTPS.\n\nОтправляйте запросы только со своего сервера. Не вызывайте API из браузера или мобильного приложения: в их код пришлось бы положить секретный ключ, а там его может прочитать кто угодно. Браузер такой запрос и не выполнит: API не разрешает запросы со страниц сайтов (CORS выключен).\n\nAPI использует HTTP Basic:\n\n- логин — **ID магазина**, например `33661`;\n- пароль — **секретный ключ**.\n\nВ cURL это параметр `-u`. Без cURL передайте заголовок `Authorization` со словом `Basic` и строкой `<ID магазина>:<секретный ключ>` в Base64. Почти все HTTP-библиотеки собирают этот заголовок сами, если передать логин и пароль."
      }
    },
    "schemas": {
      "Payment": {
        "type": "object",
        "description": "Объект платежа (Payment) содержит всю информацию о платеже, актуальную на текущий момент времени. Он формируется при создании платежа и приходит в ответ на любой запрос, связанный с платежами.\n\nОбъект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID платежа, UUID из 36 символов. Сохраните его в заказе: по нему вы получите платёж.",
            "examples": [
              "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f"
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус платежа: `pending`, `succeeded` или `canceled`. Что делать в каждом — на странице [Статусы платежа](https://avantpay.io/developers/statuses/).",
            "examples": [
              "succeeded"
            ]
          },
          "paid": {
            "type": "boolean",
            "description": "`true`, если платёж оплачен (`status` равен `succeeded`). Иначе `false`.",
            "examples": [
              true
            ]
          },
          "amount": {
            "type": "object",
            "description": "Сумма платежа — ровно та, что вы передали при создании. Покупатель платит эту сумму.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой с двумя знаками после точки.",
                "examples": [
                  "1000.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "income_amount": {
            "type": "object",
            "description": "Сколько получит магазин: `amount` минус комиссия AvantPay. Бывает только у платежей со статусом `succeeded`. Может не быть и у них, например пока AvantPay проверяет оплату. Не решайте по этому полю, оплачен ли платёж.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой с двумя знаками после точки.",
                "examples": [
                  "975.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "description": {
            "type": "string",
            "description": "Описание, которое вы передали при создании. Есть, только если вы его передали.",
            "examples": [
              "Заказ №123"
            ]
          },
          "recipient": {
            "type": "object",
            "description": "Получатель платежа — ваш магазин.",
            "properties": {
              "account_id": {
                "type": "string",
                "description": "ID магазина строкой.",
                "examples": [
                  "33661"
                ]
              },
              "gateway_id": {
                "type": "string",
                "description": "ID счёта в AvantPay, на который зачисляются деньги. Появляется, когда выбран способ оплаты. Для интеграции не нужен.",
                "examples": [
                  "6b1f3c0a-58e2-4f7d-9a41-0c2d7e5b8f93"
                ]
              }
            },
            "required": [
              "account_id"
            ]
          },
          "payment_method": {
            "description": "Способ оплаты. Появляется, когда способ выбран: сразу, если вы передали `payment_method_data`, иначе — когда покупатель выберет способ на странице оплаты. Если магазину подключены другие способы, `type` может быть и другим — на незнакомом значении код не должен падать.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/PaymentPaymentMethodSbp"
              },
              {
                "$ref": "#/components/schemas/PaymentPaymentMethodBankCard"
              },
              {
                "$ref": "#/components/schemas/PaymentPaymentMethodCrypto"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "sbp": "#/components/schemas/PaymentPaymentMethodSbp",
                "bank_card": "#/components/schemas/PaymentPaymentMethodBankCard",
                "crypto": "#/components/schemas/PaymentPaymentMethodCrypto"
              }
            }
          },
          "captured_at": {
            "type": "string",
            "description": "Когда платёж оплачен. Бывает только у платежей со статусом `succeeded`. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-18T10:17:02.418Z`.",
            "format": "date-time",
            "examples": [
              "2026-10-18T10:17:02.418Z"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Когда платёж создан. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-18T10:15:30.123Z`.",
            "format": "date-time",
            "examples": [
              "2026-10-18T10:15:30.123Z"
            ]
          },
          "expires_at": {
            "type": "string",
            "description": "До какого момента покупатель может заплатить: 20 минут после создания платежа, у сценария `qr` — срок QR-кода (10 минут после выдачи). Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-18T10:35:30.123Z`.",
            "format": "date-time",
            "examples": [
              "2026-10-18T10:35:30.123Z"
            ]
          },
          "confirmation": {
            "description": "Как покупатель платит — сценарий, который вы передали при создании. Нет у платежа со сценарием `qr`, у которого нет QR-кода: AvantPay отклонил платёж при создании (`canceled`, причина `fraud_suspected`), банк не выдал QR-код (`canceled`) или QR-код ещё выдаётся (`pending` после ответа 202 на создание: повторите запрос создания с тем же `Idempotence-Key`).",
            "oneOf": [
              {
                "$ref": "#/components/schemas/PaymentConfirmationRedirect"
              },
              {
                "$ref": "#/components/schemas/PaymentConfirmationQr"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "redirect": "#/components/schemas/PaymentConfirmationRedirect",
                "qr": "#/components/schemas/PaymentConfirmationQr"
              }
            }
          },
          "test": {
            "type": "boolean",
            "description": "Тестовый ли платёж. Всегда `false`: тестового режима нет.",
            "examples": [
              false
            ]
          },
          "refunded_amount": {
            "type": "object",
            "description": "Сколько денег уже вернули покупателю: сумма выполненных возвратов (статус `succeeded`) — через API и в личном кабинете. Есть, только если был выполненный возврат. Статус платежа после возврата остаётся `succeeded`.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой с двумя знаками после точки.",
                "examples": [
                  "300.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "refundable": {
            "type": "boolean",
            "description": "Можно ли сейчас вернуть платёж запросом [`POST /v3/refunds`](https://avantpay.io/developers/api/#create_refund). `true` — запрос пройдёт проверки. `false` — нельзя: платёж не оплачен, уже возвращён полностью, по нему идёт другой возврат или вернуть его можно только через поддержку. Право ключа «Возвраты» и деньги на счёте магазина здесь не учитываются.",
            "examples": [
              true
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Ваши данные из запроса на создание: email покупателя, номер заказа и другие ключи, которые вы передали. Значения — строки.",
            "properties": {
              "email": {
                "type": "string",
                "description": "Email покупателя, который вы передали. У автоплатежа по `payment_method_id` — только если вы его передали.",
                "examples": [
                  "buyer@example.com"
                ]
              },
              "order_id": {
                "type": "string",
                "description": "Номер заказа, если вы его передали.",
                "examples": [
                  "123"
                ]
              }
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "cancellation_details": {
            "type": "object",
            "description": "Кто отменил платёж и почему. Бывает только у платежей со статусом `canceled`.",
            "properties": {
              "party": {
                "type": "string",
                "description": "Кто отменил: `merchant`, `avantpay` или `payment_network`. Что значит каждое — на странице [Статусы платежа](https://avantpay.io/developers/statuses/#cancellation).",
                "examples": [
                  "avantpay"
                ]
              },
              "reason": {
                "type": "string",
                "description": "Причина отмены. Все причины — на странице [Статусы платежа](https://avantpay.io/developers/statuses/#reasons).",
                "examples": [
                  "expired_on_confirmation"
                ]
              }
            },
            "required": [
              "party",
              "reason"
            ]
          }
        },
        "required": [
          "id",
          "status",
          "paid",
          "amount",
          "recipient",
          "created_at",
          "expires_at",
          "test",
          "refundable",
          "metadata"
        ]
      },
      "PaymentPaymentMethodSbp": {
        "type": "object",
        "description": "Способ оплаты: СБП.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `sbp`.",
            "examples": [
              "sbp"
            ],
            "const": "sbp"
          },
          "id": {
            "type": "string",
            "description": "ID способа оплаты. У сохранённого способа — его ID: передавайте его в `payment_method_id` для автоплатежей ([способы оплаты](https://avantpay.io/developers/api/#payment_method_object)). У несохранённого равен `id` платежа.",
            "examples": [
              "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
            ]
          },
          "saved": {
            "type": "boolean",
            "description": "`true` — способ сохранён для автоплатежей.",
            "examples": [
              true
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус сохранения: `pending` — платёж с `save_payment_method` ждёт оплаты, `active` — способ сохранён, `inactive` — не сохранён.",
            "examples": [
              "active"
            ]
          },
          "title": {
            "type": "string",
            "description": "Название способа.",
            "examples": [
              "СБП"
            ]
          }
        },
        "required": [
          "type",
          "id",
          "saved",
          "status"
        ]
      },
      "PaymentPaymentMethodBankCard": {
        "type": "object",
        "description": "Способ оплаты: банковская карта.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `bank_card`.",
            "examples": [
              "bank_card"
            ],
            "const": "bank_card"
          },
          "id": {
            "type": "string",
            "description": "ID способа оплаты. У сохранённого способа — его ID: передавайте его в `payment_method_id` для автоплатежей ([способы оплаты](https://avantpay.io/developers/api/#payment_method_object)). У несохранённого равен `id` платежа.",
            "examples": [
              "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
            ]
          },
          "saved": {
            "type": "boolean",
            "description": "`true` — способ сохранён для автоплатежей.",
            "examples": [
              true
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус сохранения: `pending` — платёж с `save_payment_method` ждёт оплаты, `active` — способ сохранён, `inactive` — не сохранён.",
            "examples": [
              "active"
            ]
          },
          "title": {
            "type": "string",
            "description": "Название способа.",
            "examples": [
              "Банковская карта"
            ]
          },
          "card": {
            "type": "object",
            "description": "Данные карты. Есть у сохранённого способа.",
            "properties": {
              "first6": {
                "type": "string",
                "description": "Первые 6 цифр номера карты (BIN).",
                "examples": [
                  "220220"
                ]
              },
              "last4": {
                "type": "string",
                "description": "Последние 4 цифры номера карты.",
                "examples": [
                  "4444"
                ]
              },
              "expiry_month": {
                "type": "string",
                "description": "Месяц окончания срока действия, `MM`.",
                "examples": [
                  "07"
                ]
              },
              "expiry_year": {
                "type": "string",
                "description": "Год окончания срока действия, `YYYY`.",
                "examples": [
                  "2030"
                ]
              },
              "card_type": {
                "type": "string",
                "description": "Платёжная система: `Mir`, `Visa`, `MasterCard`, `UnionPay` или `Unknown`.",
                "examples": [
                  "Mir"
                ]
              },
              "issuer_country": {
                "type": "string",
                "description": "Страна банка-эмитента, код ISO 3166-1 alpha-2.",
                "examples": [
                  "RU"
                ]
              },
              "issuer_name": {
                "type": "string",
                "description": "Банк-эмитент.",
                "examples": [
                  "Sberbank"
                ]
              }
            },
            "required": [
              "last4",
              "card_type"
            ]
          }
        },
        "required": [
          "type",
          "id",
          "saved",
          "status"
        ]
      },
      "PaymentPaymentMethodCrypto": {
        "type": "object",
        "description": "Способ оплаты: криптовалюта.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `crypto`.",
            "examples": [
              "crypto"
            ],
            "const": "crypto"
          },
          "id": {
            "type": "string",
            "description": "ID способа оплаты. У сохранённого способа — его ID: передавайте его в `payment_method_id` для автоплатежей ([способы оплаты](https://avantpay.io/developers/api/#payment_method_object)). У несохранённого равен `id` платежа.",
            "examples": [
              "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
            ]
          },
          "saved": {
            "type": "boolean",
            "description": "`true` — способ сохранён для автоплатежей.",
            "examples": [
              true
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус сохранения: `pending` — платёж с `save_payment_method` ждёт оплаты, `active` — способ сохранён, `inactive` — не сохранён.",
            "examples": [
              "active"
            ]
          },
          "title": {
            "type": "string",
            "description": "Название способа.",
            "examples": [
              "Криптовалюта"
            ]
          }
        },
        "required": [
          "type",
          "id",
          "saved",
          "status"
        ]
      },
      "PaymentConfirmationRedirect": {
        "type": "object",
        "description": "Сценарий: страница оплаты.",
        "properties": {
          "type": {
            "type": "string",
            "description": "`redirect` — страница оплаты AvantPay.",
            "examples": [
              "redirect"
            ],
            "const": "redirect"
          },
          "confirmation_url": {
            "type": "string",
            "description": "Ссылка на страницу оплаты. Отправьте покупателя по ней, только если `status` равен `pending`. Может не быть у платежа, который отменён при создании.",
            "examples": [
              "https://avantpay.io/checkout?paymentId=2b6aa501-0b3c-4f8e-9d1a-5c7e3f2aec08"
            ]
          },
          "return_url": {
            "type": "string",
            "description": "Адрес возврата покупателя, который вы передали.",
            "examples": [
              "https://example.com/orders/123"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "PaymentConfirmationQr": {
        "type": "object",
        "description": "Сценарий: QR-код СБП.",
        "properties": {
          "type": {
            "type": "string",
            "description": "`qr` — QR-код СБП.",
            "examples": [
              "qr"
            ],
            "const": "qr"
          },
          "confirmation_data": {
            "type": "string",
            "description": "Ссылка СБП от банка — содержимое QR-кода, обычно `https://qr.nspk.ru/…`. Есть уже в ответе на создание платежа и не меняется: QR-код у платежа один и действует до `expires_at`, нового AvantPay не выдаёт. Сделайте из ссылки QR-код и покажите покупателю, на телефоне ссылку можно просто открыть. Страницы оплаты AvantPay здесь не бывает.",
            "examples": [
              "https://qr.nspk.ru/AD10006M8KHABCDEFG"
            ]
          }
        },
        "required": [
          "type"
        ]
      },
      "PaymentMethod": {
        "type": "object",
        "description": "Объект способа оплаты (PaymentMethod) содержит информацию о способе оплаты, сохранённом для автоплатежей: тип, статус и данные карты или банка. Способ сохраняется платежом с `save_payment_method: true` или [запросом на создание](https://avantpay.io/developers/api/#create_payment_method). Как проводить автоплатежи — на странице [Автоплатежи](https://avantpay.io/developers/recurring/).\n\nОбъект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Тип способа оплаты: `bank_card` или `sbp`.",
            "examples": [
              "bank_card"
            ]
          },
          "id": {
            "type": "string",
            "description": "ID способа оплаты. Передавайте его в `payment_method_id` при [создании платежа](https://avantpay.io/developers/api/#create_payment) для автоплатежа.",
            "examples": [
              "9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
            ]
          },
          "saved": {
            "type": "boolean",
            "description": "`true` — способ сохранён: по нему можно проводить автоплатежи.",
            "examples": [
              true
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус способа оплаты: `pending` — ждёт действий покупателя, `active` — сохранён, `inactive` — не сохранён (ошибка, истёк срок привязки) или покупатель отключил автоплатежи.",
            "examples": [
              "active"
            ]
          },
          "title": {
            "type": "string",
            "description": "Название способа оплаты.",
            "examples": [
              "Bank card *4444"
            ]
          },
          "card": {
            "type": "object",
            "description": "Данные карты. Есть у сохранённой карты (`bank_card`).",
            "properties": {
              "first6": {
                "type": "string",
                "description": "Первые 6 цифр номера карты (BIN).",
                "examples": [
                  "220220"
                ]
              },
              "last4": {
                "type": "string",
                "description": "Последние 4 цифры номера карты.",
                "examples": [
                  "4444"
                ]
              },
              "expiry_month": {
                "type": "string",
                "description": "Месяц окончания срока действия, `MM`.",
                "examples": [
                  "07"
                ]
              },
              "expiry_year": {
                "type": "string",
                "description": "Год окончания срока действия, `YYYY`.",
                "examples": [
                  "2030"
                ]
              },
              "card_type": {
                "type": "string",
                "description": "Платёжная система: `Mir`, `Visa`, `MasterCard`, `UnionPay` или `Unknown`.",
                "examples": [
                  "Mir"
                ]
              },
              "issuer_country": {
                "type": "string",
                "description": "Страна банка-эмитента, код ISO 3166-1 alpha-2.",
                "examples": [
                  "RU"
                ]
              },
              "issuer_name": {
                "type": "string",
                "description": "Банк-эмитент.",
                "examples": [
                  "Sberbank"
                ]
              }
            },
            "required": [
              "last4",
              "card_type"
            ]
          },
          "holder": {
            "type": "object",
            "description": "Магазин, для которого сохранён способ оплаты.",
            "properties": {
              "account_id": {
                "type": "string",
                "description": "ID магазина.",
                "examples": [
                  "33661"
                ]
              }
            },
            "required": [
              "account_id"
            ]
          },
          "payer_bank_details": {
            "type": "object",
            "description": "Банк покупателя. Есть у СБП (`sbp`), если банк известен.",
            "properties": {
              "bank_id": {
                "type": "string",
                "description": "ID банка в СБП.",
                "examples": [
                  "100000000111"
                ]
              }
            },
            "required": [
              "bank_id"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Ваши данные из запроса на создание способа оплаты. Есть, только если вы их передали.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "confirmation": {
            "type": "object",
            "description": "Подтверждение способа оплаты покупателем. Есть у способа в статусе `pending`, созданного [запросом](https://avantpay.io/developers/api/#create_payment_method).",
            "properties": {
              "type": {
                "type": "string",
                "description": "Значение — `redirect`.",
                "examples": [
                  "redirect"
                ]
              },
              "confirmation_url": {
                "type": "string",
                "description": "Ссылка, по которой покупатель подтверждает сохранение карты. Перенаправьте его по ней.",
                "examples": [
                  "https://avantpay.io/checkout/bind?paymentMethodId=9d4c2b1a-6e5f-4a3b-8c7d-1e2f3a4b5c6d"
                ]
              },
              "return_url": {
                "type": "string",
                "description": "Куда вернётся покупатель — из запроса на создание.",
                "examples": [
                  "https://example.com/account/cards"
                ]
              }
            },
            "required": [
              "type",
              "confirmation_url"
            ]
          }
        },
        "required": [
          "type",
          "id",
          "saved",
          "status",
          "holder"
        ]
      },
      "Refund": {
        "type": "object",
        "description": "Объект возврата (Refund) содержит всю информацию о возврате, актуальную на текущий момент времени. Он формируется при создании возврата и приходит в ответ на любой запрос, связанный с возвратами. Как сделать возврат — на странице [Возвраты](https://avantpay.io/developers/refunds/).\n\nОбъект может содержать параметры и значения, не описанные в этом Справочнике API. Их следует игнорировать.",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID возврата, UUID из 36 символов. Сохраните его: по нему вы узнаете, чем кончился возврат.",
            "examples": [
              "5e1d7c3a-9b2f-4a6e-8d4c-0f3b2a1e9c87"
            ]
          },
          "payment_id": {
            "type": "string",
            "description": "ID платежа, по которому сделан возврат.",
            "examples": [
              "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f"
            ]
          },
          "status": {
            "type": "string",
            "description": "Статус возврата: `pending`, `succeeded` или `canceled`. Что значит каждый — в разделе [Статусы возврата](https://avantpay.io/developers/api/#refund_object-statuses).",
            "examples": [
              "succeeded"
            ]
          },
          "cancellation_details": {
            "type": "object",
            "description": "Кто отменил возврат и почему. Бывает только у возвратов со статусом `canceled`.",
            "properties": {
              "party": {
                "type": "string",
                "description": "Кто отменил: `avantpay` или `refund_network`. Что значит каждое — в разделе [Кто отменил возврат](https://avantpay.io/developers/api/#refund_object-cancellation).",
                "examples": [
                  "avantpay"
                ]
              },
              "reason": {
                "type": "string",
                "description": "Причина отмены: `insufficient_funds` или `general_decline`. Что делать — в разделе [Кто отменил возврат](https://avantpay.io/developers/api/#refund_object-cancellation).",
                "examples": [
                  "insufficient_funds"
                ]
              }
            },
            "required": [
              "party",
              "reason"
            ]
          },
          "created_at": {
            "type": "string",
            "description": "Когда возврат создан. Указывается по [UTC](https://ru.wikipedia.org/wiki/%D0%92%D1%81%D0%B5%D0%BC%D0%B8%D1%80%D0%BD%D0%BE%D0%B5_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5_%D0%B2%D1%80%D0%B5%D0%BC%D1%8F) и передаётся в формате [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Пример: `2026-10-19T09:40:12.305Z`.",
            "format": "date-time",
            "examples": [
              "2026-10-19T09:40:12.305Z"
            ]
          },
          "amount": {
            "type": "object",
            "description": "Сумма возврата — та, что вы передали при создании. В валюте платежа.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой с двумя знаками после точки.",
                "examples": [
                  "300.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "description": {
            "type": "string",
            "description": "Комментарий, который вы передали при создании. Есть, только если вы его передали.",
            "examples": [
              "Возврат по заказу №123"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Ваши произвольные данные из запроса на создание возврата. Значения — строки. Если вы их не передали или возврат сделан в личном кабинете — пустой объект `{}`.",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "payment_id",
          "status",
          "created_at",
          "amount",
          "metadata"
        ]
      },
      "Notification": {
        "type": "object",
        "description": "Уведомление — POST-запрос от AvantPay на ваш сервер о событии ([Уведомления](https://avantpay.io/developers/webhooks/)).\n\nЗапрос приходит с заголовком `Content-Type: application/json` и телом из трёх полей:",
        "properties": {
          "type": {
            "type": "string",
            "description": "Всегда `notification`.",
            "examples": [
              "notification"
            ]
          },
          "event": {
            "type": "string",
            "description": "Событие: `payment.succeeded`, `payment.canceled`, `refund.succeeded` или `payment_method.active`.",
            "examples": [
              "payment.succeeded"
            ]
          },
          "object": {
            "type": "object",
            "description": "Объект на момент события. У `payment.succeeded` и `payment.canceled` — [объект платежа](https://avantpay.io/developers/api/#payment_object), как в ответе на `GET /v3/payments/{payment_id}`. У `refund.succeeded` — [объект возврата](https://avantpay.io/developers/api/#refund_object), как в ответе на `GET /v3/refunds/{refund_id}`. У `payment_method.active` — [объект способа оплаты](https://avantpay.io/developers/api/#payment_method_object), как в ответе на `GET /v3/payment_methods/{payment_method_id}`."
          }
        },
        "required": [
          "type",
          "event",
          "object"
        ]
      },
      "ApiError": {
        "type": "object",
        "description": "Если запрос не выполнен, API отвечает кодом HTTP 400 или выше и объектом ошибки. Объект ошибки приходит на любой ответ 4xx и 5xx, в том числе на неверный адрес (404), неверный метод HTTP (405) и запрос без JSON (415).",
        "properties": {
          "type": {
            "type": "string",
            "description": "Всегда `error`.",
            "examples": [
              "error"
            ]
          },
          "id": {
            "type": "string",
            "description": "ID ошибки. Укажите его, если пишете в поддержку.",
            "examples": [
              "6daac9fa-342d-4264-91c5-b5eafd1a0010"
            ]
          },
          "code": {
            "type": "string",
            "description": "Код ошибки из таблицы ниже. По нему решайте, что делать.",
            "examples": [
              "invalid_request"
            ]
          },
          "description": {
            "type": "string",
            "description": "Что не так и как исправить. На английском. Пишите в логи, покупателю не показывайте.",
            "examples": [
              "Invalid request"
            ]
          },
          "parameter": {
            "type": "string",
            "description": "Какое поле, заголовок или параметр неверны. Например: `amount.value`, `metadata.email`, `Idempotence-Key`, `Authorization`, `payment_id`, `refund_id`, `limit`.",
            "examples": [
              "metadata.email"
            ]
          },
          "retry_after": {
            "type": "integer",
            "description": "Через сколько миллисекунд повторить запрос. Есть у ответов 429.",
            "examples": [
              1000
            ]
          }
        },
        "required": [
          "type",
          "id",
          "code",
          "description"
        ]
      },
      "Processing": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "examples": [
              "processing"
            ]
          },
          "description": {
            "type": "string",
            "examples": [
              "Request accepted"
            ]
          },
          "retry_after": {
            "type": "integer",
            "examples": [
              2000
            ]
          }
        },
        "required": [
          "type",
          "description",
          "retry_after"
        ]
      },
      "CreatePaymentRequest": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "object",
            "description": "Сумма платежа. Покупатель заплатит ровно её. Комиссию AvantPay платит магазин: она вычитается из этой суммы.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой, рубли и копейки через точку. Больше нуля, не больше двух знаков после точки. Должна укладываться в лимиты способов оплаты — они есть в личном кабинете: **Ещё → Способы оплаты**.",
                "examples": [
                  "1000.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "capture": {
            "type": "boolean",
            "description": "Указывается `true`.",
            "examples": [
              true
            ]
          },
          "confirmation": {
            "description": "Обязательно без `payment_method_id`. Как покупатель будет платить.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/CreatePaymentRequestConfirmationRedirect"
              },
              {
                "$ref": "#/components/schemas/CreatePaymentRequestConfirmationQr"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "redirect": "#/components/schemas/CreatePaymentRequestConfirmationRedirect",
                "qr": "#/components/schemas/CreatePaymentRequestConfirmationQr"
              }
            }
          },
          "description": {
            "type": "string",
            "description": "Описание платежа, до 128 символов. Его видит покупатель на странице оплаты и вы в личном кабинете.",
            "examples": [
              "Заказ №123"
            ]
          },
          "payment_method_data": {
            "description": "Способ оплаты. Если не передать, покупатель выберет способ на странице оплаты. Способ должен быть включён у магазина.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/CreatePaymentRequestPaymentMethodDataSbp"
              },
              {
                "$ref": "#/components/schemas/CreatePaymentRequestPaymentMethodDataBankCard"
              },
              {
                "$ref": "#/components/schemas/CreatePaymentRequestPaymentMethodDataErip"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "sbp": "#/components/schemas/CreatePaymentRequestPaymentMethodDataSbp",
                "bank_card": "#/components/schemas/CreatePaymentRequestPaymentMethodDataBankCard",
                "erip": "#/components/schemas/CreatePaymentRequestPaymentMethodDataErip"
              }
            }
          },
          "client_ip": {
            "type": "string",
            "description": "IP-адрес покупателя, IPv4 или IPv6.",
            "examples": [
              "203.0.113.7"
            ]
          },
          "save_payment_method": {
            "type": "boolean",
            "description": "`true` — сохранить способ оплаты для автоплатежей. ID сохранённого способа — `payment_method.id` в ответе ([подробнее](https://avantpay.io/developers/recurring/)).",
            "examples": [
              true
            ]
          },
          "payment_method_id": {
            "type": "string",
            "description": "ID сохранённого способа оплаты, до 64 символов: списание без участия покупателя. `confirmation` и `metadata.email` не нужны ([подробнее](https://avantpay.io/developers/recurring/)).",
            "examples": [
              "2b6aa501-cb83-493d-b169-e00f2156ec08"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Обязательно без `payment_method_id`. Ваши данные к платежу. Обязателен ключ `email`. Всего до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте платежа и в уведомлениях. Подробнее — в разделе [metadata](https://avantpay.io/developers/api/#format-metadata).",
            "properties": {
              "email": {
                "type": "string",
                "description": "Обязательно без `payment_method_id`. Email покупателя, до 254 символов. Покупатель из Telegram — `<telegram_id>@telegram.org`, например `123456789@telegram.org`. Нет email или адрес неверный — ошибка 400 `invalid_request`, `parameter` — `metadata.email`.",
                "examples": [
                  "buyer@example.com"
                ]
              },
              "order_id": {
                "type": "string",
                "description": "Ваш номер заказа. Вернётся в объекте платежа и в уведомлениях. API не проверяет, что номер уникален: от двойного платежа защищает ключ идемпотентности.",
                "examples": [
                  "123"
                ]
              }
            },
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "amount",
          "capture"
        ]
      },
      "CreatePaymentRequestConfirmationRedirect": {
        "type": "object",
        "description": "Сценарий: страница оплаты.",
        "properties": {
          "type": {
            "type": "string",
            "description": "`redirect` — покупатель переходит на страницу оплаты AvantPay.",
            "examples": [
              "redirect"
            ],
            "const": "redirect"
          },
          "return_url": {
            "type": "string",
            "description": "Куда вернуть покупателя после оплаты или отказа от неё. Адрес `http://` или `https://`, до 2048 символов. AvantPay открывает его как есть, без параметров, поэтому укажите в нём свой заказ.",
            "examples": [
              "https://example.com/orders/123"
            ]
          }
        },
        "required": [
          "type",
          "return_url"
        ]
      },
      "CreatePaymentRequestConfirmationQr": {
        "type": "object",
        "description": "Сценарий: QR-код СБП.",
        "properties": {
          "type": {
            "type": "string",
            "description": "`qr` — вы показываете покупателю QR-код СБП. Только вместе с `\"payment_method_data\": {\"type\": \"sbp\"}`. Ссылка для QR-кода — `confirmation.confirmation_data` в ответе на создание. Если банк выдаёт QR-код дольше 10 секунд, API ответит 202: повторите запрос с тем же `Idempotence-Key`. QR-код не выдан — платёж `canceled` без `confirmation`.",
            "examples": [
              "qr"
            ],
            "const": "qr"
          },
          "return_url": {
            "type": "string",
            "description": "Куда вернуть покупателя после оплаты или отказа от неё. Адрес `http://` или `https://`, до 2048 символов. AvantPay открывает его как есть, без параметров, поэтому укажите в нём свой заказ.",
            "examples": [
              "https://example.com/orders/123"
            ]
          }
        },
        "required": [
          "type",
          "return_url"
        ]
      },
      "CreatePaymentRequestPaymentMethodDataSbp": {
        "type": "object",
        "description": "Способ оплаты: СБП.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `sbp`.",
            "examples": [
              "sbp"
            ],
            "const": "sbp"
          }
        },
        "required": [
          "type"
        ]
      },
      "CreatePaymentRequestPaymentMethodDataBankCard": {
        "type": "object",
        "description": "Способ оплаты: банковская карта.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `bank_card`.",
            "examples": [
              "bank_card"
            ],
            "const": "bank_card"
          }
        },
        "required": [
          "type"
        ]
      },
      "CreatePaymentRequestPaymentMethodDataErip": {
        "type": "object",
        "description": "Способ оплаты: ЕРИП.",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `erip`. ЕРИП (Беларусь). Только со сценарием `redirect`.",
            "examples": [
              "erip"
            ],
            "const": "erip"
          }
        },
        "required": [
          "type"
        ]
      },
      "GetPaymentsListResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Всегда `list`.",
            "examples": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "description": "Платежи — [объекты платежа](https://avantpay.io/developers/api/#payment_object), от новых к старым. Если ничего не нашлось — пустой массив `[]`.",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Курсор следующей страницы. Нет на последней странице.",
            "examples": [
              "MjAyNi0xMC0xN1QxODozOTo1NS44NzFa"
            ]
          }
        },
        "required": [
          "type",
          "items"
        ]
      },
      "CreatePaymentMethodRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Значение — `bank_card`. СБП без платежа не сохраняется: создайте платёж с `save_payment_method: true`.",
            "examples": [
              "bank_card"
            ]
          },
          "confirmation": {
            "type": "object",
            "description": "Сценарий подтверждения: покупатель переходит по ссылке и подтверждает карту, на ней блокируется и сразу возвращается 1 ₽.",
            "properties": {
              "type": {
                "type": "string",
                "description": "Значение — `redirect`.",
                "examples": [
                  "redirect"
                ]
              },
              "return_url": {
                "type": "string",
                "description": "Куда вернуть покупателя после подтверждения. Адрес `http://` или `https://`, до 2048 символов.",
                "examples": [
                  "https://example.com/account/cards"
                ]
              }
            },
            "required": [
              "type",
              "return_url"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Ваши данные к способу оплаты: до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте способа оплаты.",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "type",
          "confirmation"
        ]
      },
      "CreateRefundRequest": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "description": "`id` платежа, который нужно вернуть, — 36 символов. Платёж вашего магазина в статусе `succeeded`: проверьте, что у него `refundable` равен `true`.",
            "examples": [
              "2f9b6c1e-4d7a-4c3b-9e8f-1a2b3c4d5e6f"
            ]
          },
          "amount": {
            "type": "object",
            "description": "Сумма возврата: вся сумма платежа или часть. Со счёта магазина спишется вся эта сумма.",
            "properties": {
              "value": {
                "type": "string",
                "description": "Сумма строкой, рубли и копейки через точку, не больше двух знаков после точки. Не больше остатка — суммы платежа минус уже возвращённое. Не меньше 1 ₽: меньше можно вернуть, только если это весь остаток.",
                "examples": [
                  "300.00"
                ]
              },
              "currency": {
                "type": "string",
                "description": "Валюта платежа: `RUB`.",
                "examples": [
                  "RUB"
                ]
              }
            },
            "required": [
              "value",
              "currency"
            ]
          },
          "description": {
            "type": "string",
            "description": "Комментарий к возврату, до 250 символов. Вернётся в объекте возврата.",
            "examples": [
              "Возврат по заказу №123"
            ]
          },
          "metadata": {
            "type": "object",
            "description": "Ваши произвольные данные к возврату. Правила — как у `metadata` платежа, но `email` не нужен: до 16 ключей, имя ключа до 32 символов, значение — строка до 512 символов. Вернутся в объекте возврата и в уведомлении `refund.succeeded`. Подробнее — в разделе [metadata](https://avantpay.io/developers/api/#format-metadata).",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "payment_id",
          "amount"
        ]
      },
      "GetRefundsListResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Всегда `list`.",
            "examples": [
              "list"
            ]
          },
          "items": {
            "type": "array",
            "description": "Возвраты — [объекты возврата](https://avantpay.io/developers/api/#refund_object), от новых к старым. Если ничего не нашлось — пустой массив `[]`.",
            "items": {
              "$ref": "#/components/schemas/Refund"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Курсор следующей страницы. Нет на последней странице.",
            "examples": [
              "MjAyNi0xMC0xN1QxODozOTo1NS44NzFa"
            ]
          }
        },
        "required": [
          "type",
          "items"
        ]
      }
    }
  }
}
