ЮKassa API

Отрасль: Платежи и финансы. Актуально на 2026-10-11.

REST API ЮKassa для приема онлайн-платежей: создание и подтверждение платежей, возвраты, чеки по 54-ФЗ, автоплатежи, счета, выплаты и Безопасная сделка. Запросы — POST, GET и DELETE по HTTPS, тело POST-запросов в JSON, ответы всегда в JSON. Аутентификация — HTTP Basic: идентификатор магазина и секретный ключ.

Охват

Есть:

• Платежи: создание, подтверждение, отмена, статус и выгрузка списка
• Возвраты: полные и частичные
• Чеки по 54-ФЗ вместе с платежом
• Автоплатежи по сохраненному способу оплаты
• Входящие HTTP-уведомления: настройка, события, проверка подлинности
• Все методы API v3 с параметрами из официальной спецификации: счета, выплаты, Безопасная сделка, кассовые ссылки, участники СБП, персональные данные, webhook для партнеров, настройки магазина

Нет — смотри официальную документацию:

• Полные схемы объектов (платеж, возврат, чек, выплата) — у методов только основные поля
• Виджет ЮKassa, Checkout.js и мобильные SDK
• Готовые SDK для PHP, Python и других языков
• Сценарии выплат, Сплитования платежей и Безопасной сделки целиком
• Полные справочники для чеков: признаки предмета и способа расчета, отраслевые реквизиты, маркировка

Сценарии

Принять оплату с переадресацией на ЮKassa

Покупатель платит на странице ЮKassa и возвращается на сайт. Подходит большинству интернет-магазинов.

1. Создай платеж: POST /payments с amount, capture: true, confirmation.type = redirect и confirmation.return_url. Передай заголовок Idempotence-Key — новый для каждой новой операции.
2. Сохрани id платежа в заказе и перенаправь покупателя по ссылке confirmation.confirmation_url из ответа.
3. Когда покупатель вернется на return_url, проверь статус на сервере: GET /payments/{payment_id}. Оплата прошла, если status = succeeded.
4. Если status = canceled, причина — в cancellation_details. Для повторной попытки создай новый платеж с новым ключом идемпотентности.

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {"value": "1000.00", "currency": "RUB"},
        "capture": true,
        "confirmation": {"type": "redirect", "return_url": "https://example.ru/orders/72"},
        "description": "Оплата заказа № 72",
        "metadata": {"order_id": "72"}
      }'

Двухстадийная оплата: заблокировать и списать

Деньги сначала холдируются на счете покупателя и списываются, когда вы подтвердите заказ.

1. Создай платеж с capture: false: POST /payments. По умолчанию capture и так false.
2. После оплаты платеж переходит в статус waiting_for_capture. Срок, до которого его можно подтвердить или отменить, — в поле expires_at.
3. Спиши деньги: POST /payments/{payment_id}/capture. В amount можно передать часть суммы, если способ оплаты поддерживает частичное списание, — остаток вернется покупателю.
4. Если заказ не состоится, отмени платеж: POST /payments/{payment_id}/cancel. Платеж, не подтвержденный до expires_at, отменится сам, а деньги вернутся покупателю.

curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{"amount": {"value": "1000.00", "currency": "RUB"}}'

Вернуть деньги покупателю

Полный или частичный возврат успешного платежа.

1. Проверь платеж: GET /payments/{payment_id}. Вернуть можно платеж в статусе succeeded, если refundable = true.
2. Создай возврат: POST /refunds с payment_id и amount — всей суммой или ее частью. Если используешь чеки, передай receipt.
3. Проверь итог: GET /refunds/{refund_id}. Финальные статусы — succeeded и canceled; причина отмены — в cancellation_details.

curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
      }'

Отправить чек по 54-ФЗ вместе с платежом

Для компаний и ИП, которые используют Чеки от ЮKassa или стороннюю онлайн-кассу.

1. Добавь в POST /payments объект receipt: receipt.customer с контактом покупателя (для Чеков от ЮKassa — email) и receipt.items — список позиций.
2. Для каждой позиции обязательны description, quantity, amount и vat_code. Для Чеков от ЮKassa vat_code: 1 — без НДС, 2 — 0%, 3 — 10%, 11 — 22%.
3. Укажи payment_subject (commodity — товар, service — услуга) и payment_mode (full_payment — полный расчет, full_prepayment — полная предоплата). Для сторонних касс значения сверь с официальной документацией.
4. Проверь, что чек зарегистрирован: GET /receipts с payment_id платежа.

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {"value": "1000.00", "currency": "RUB"},
        "capture": true,
        "confirmation": {"type": "redirect", "return_url": "https://example.ru/orders/72"},
        "description": "Оплата заказа № 72",
        "receipt": {
          "customer": {"email": "user@example.ru"},
          "items": [
            {
              "description": "Кружка",
              "quantity": 1,
              "amount": {"value": "1000.00", "currency": "RUB"},
              "vat_code": 1,
              "payment_subject": "commodity",
              "payment_mode": "full_payment"
            }
          ]
        }
      }'

Автоплатежи: сохранить способ оплаты и списывать без покупателя

Для подписок и повторных списаний. Сохранение способа оплаты доступно после согласования с менеджером ЮKassa.

1. Создай первый платеж с save_payment_method: true: POST /payments. Покупатель подтверждает его как обычно.
2. После успешной оплаты проверь в ответе GET /payments/{payment_id}, что payment_method.saved = true, и сохрани payment_method.id.
3. Для следующих списаний создай платеж с payment_method_id = сохраненный id: POST /payments. Подтверждение покупателя не требуется.

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {"value": "2.00", "currency": "RUB"},
        "capture": true,
        "payment_method_id": "<Идентификатор сохраненного способа оплаты>",
        "description": "Заказ №37"
      }'

Узнавать об оплате через HTTP-уведомления

ЮKassa сама сообщает о смене статуса платежа или возврата, не нужно опрашивать API.

1. В личном кабинете, в разделе Интеграция — HTTP-уведомления, укажи URL и события: payment.succeeded, payment.waiting_for_capture, payment.canceled, refund.succeeded. URL — только HTTPS на порту 443 или 8443, TLS 1.2 и выше.
2. Принимай POST-запрос с объектом события и отвечай HTTP 200. На любой другой код ЮKassa повторяет отправку в течение 24 часов.
3. Проверь подлинность: запроси объект — GET /payments/{payment_id} — и сверь статус. Еще один способ — проверить IP отправителя: 185.71.76.0/27, 185.71.77.0/27, 77.75.153.0/25, 77.75.156.11, 77.75.156.35, 77.75.154.128/25, 2a02:5180::/32.
4. Партнерам с OAuth-токеном подписка доступна через API: POST /webhooks.

Выгрузить платежи за период

Для сверки и отчетов: список платежей с фильтром по дате и статусу.

1. Запроси GET /payments с created_at.gte и created_at.lt в формате ISO 8601, при необходимости — status (например, succeeded) и limit до 100.
2. Если в ответе есть next_cursor, запроси следующую страницу с cursor = next_cursor. Повторяй, пока next_cursor не исчезнет.
3. Доступны платежи, созданные за последние 3 года.

curl 'https://api.yookassa.ru/v3/payments?created_at.gte=2026-09-01T00:00:00.000Z&created_at.lt=2026-10-01T00:00:00.000Z&status=succeeded&limit=100' \
  -u <Идентификатор магазина>:<Секретный ключ>

Базовые URL

• Основной: https://api.yookassa.ru/v3

Авторизация

Тип: Basic Auth

HTTP Basic Auth: имя пользователя — идентификатор магазина (shopId, раздел Настройки — Магазин) или шлюза для выплат (agentId, раздел Настройки выплат), пароль — секретный ключ (раздел Интеграция — Ключи API). Для тестового магазина ключ выпускается автоматически. Участники партнерской программы используют OAuth 2.0 и передают Bearer-токен. Секретный ключ и OAuth-токен нельзя публиковать.

curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

Методы

POST /payments — Создание платежа

Чтобы принять платеж, нужно создать объект платежа — Payment. Он содержит всю необходимую информацию о платеже (сумму, валюту и статус). Платеж проходит линейный жизненный цикл, последовательно переходя из статуса в статус.

Документация: https://yookassa.ru/developers/api#create_payment

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
amount	body	object	да	Сумма платежа. Иногда партнеры ЮKassa берут с пользователя дополнительную комиссию, которая не входит в эту сумму. Сумма указывается вместе с кодом валюты. Валюта должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и с валютой аккаунта (shopId в личном кабинете), если не разделяете.
amount.value	body	string	да	Сумма в выбранной валюте, всегда в дробном формате. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
amount.currency	body	string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY)	да	Трехбуквенный код валюты в формате ISO-4217. Пример: RUB.
description	body	string	нет	Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru».
receipt	body	object	нет	Данные для формирования чека. Параметр передается, если вы компания или ИП и используете Чеки от ЮKassa, либо если вы компания или ИП, используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: «Платеж и чек одновременно» или «Сначала чек, потом платеж».
receipt.customer	body	object	нет	Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone).
receipt.items	body	object[]	нет	Список товаров в заказе. Если вы используете Чеки от ЮKassa, можно передать до 80 товаров, если стороннюю онлайн-кассу — до 100 товаров.
receipt.internet	body	boolean	нет	Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — платеж проведен онлайн, через интернет (например, на сайте или в приложении); false — платеж проведен офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true. Если вы принимаете платежи офлайн, передайте false.
receipt.tax_system_code	body	integer	нет	Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения; в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует.
receipt.timezone	body	integer	нет	Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс.
receipt.receipt_industry_details	body	object[]	нет	Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
receipt.receipt_operational_details	body	object	нет	Операционный реквизит чека (тег в 54 ФЗ — 1270). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
recipient	body	object	нет	Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.
recipient.gateway_id	body	string	нет	Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
payment_token	body	string	нет	Одноразовый токен для проведения оплаты, сформированный с помощью Checkout.js или мобильного SDK.
payment_method_id	body	string	нет	Идентификатор сохраненного способа оплаты.
payment_method_data	body	object	нет
payment_method_data.type	body	string (bank_card, cash, sberbank, tinkoff_bank, yoo_money, mobile_balance, b2b_sberbank, sbp)	нет
payment_method_data.card	body	object	нет	Данные банковской карты (необходимы, если вы собираете данные карты пользователей на своей стороне).
payment_method_data.phone	body	string	нет	Телефон пользователя, на который придет смс с кодом платежа (для внесения наличных). Указывается в формате ITU-T E.164, например 79000000000. Поле можно оставить пустым: пользователь сможет заполнить его при оплате на стороне ЮKassa.
payment_method_data.payment_purpose	body	string	нет	Назначение платежа (не больше 210 символов).
payment_method_data.vat_data	body	object	нет
payment_method_data.electronic_certificate	body	object	нет	Данные от ФЭС НСПК для оплаты по электронному сертификату. Неоходимо передавать только при оплате со сбором данных на вашей стороне.
payment_method_data.articles	body	object[]	нет	Корзина покупки (в терминах НСПК) — список товаров, которые можно оплатить по сертификату. Необходимо передавать только при оплате на готовой странице ЮKassa.
confirmation	body	object	нет	Данные, необходимые для инициирования выбранного сценария подтверждения платежа пользователем.
confirmation.type	body	string (redirect, external, qr, embedded, mobile_application)	нет	Код сценария подтверждения платежа пользователем. Возможные значения: redirect — перенаправление пользователя на готовую страницу ЮKassa или страницу партнера; external — ожидание, что пользователь самостоятельно подтвердит платеж; qr — формирование QR-кода и его отображение на странице оплаты, чтобы пользователь подтвердил платеж; embedded — отображение платежного виджета ЮKassa; mobile_application — перенаправление пользователя в платежное приложение партнера.
confirmation.locale	body	string (ru_RU, en_US)	нет	Язык интерфейса, писем и сообщений, которые будет видеть или получать пользователь. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен.
confirmation.enforce	body	boolean	нет	Запрос на проведение платежа с аутентификацией по 3-D Secure. Сработает, если вы по умолчанию принимаете оплату банковской картой без подтверждения платежа пользователем; в остальных случаях аутентификацией по 3-D Secure управляет ЮKassa. Чтобы принимать платежи без дополнительного подтверждения пользователем, напишите вашему менеджеру ЮKassa.
confirmation.return_url	body	string	нет	URL, на который вернется пользователь после подтверждения или отмены платежа на веб-странице. Не более 2048 символов.
save_payment_method	body	boolean	нет	Сохранение платежных данных для проведения автоплатежей. Возможные значения: * true — сохранить способ оплаты (сохранить платежные данные); * false — провести платеж без сохранения способа оплаты. Доступно только после согласования с менеджером ЮKassa.
capture	body	boolean	нет	Автоматический прием поступившего платежа. Возможные значения: * true — оплата списывается сразу (платеж в одну стадию); * false — оплата холдируется и списывается по вашему запросу (платеж в две стадии: https://yookassa.ru/developers/payment-acceptance/getting-started/payment-process#capture-and-cancel). По умолчанию false.
client_ip	body	string	нет	IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-подключения.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе ЮKassa. Ограничения: не более 16 ключей, название ключа — не больше 32 символов, значение ключа — не больше 512 символов, тип данных — строка в формате UTF-8.
airline	body	object	нет	Объект с данными для продажи авиабилетов. Используется только для платежей банковской картой.
airline.ticket_number	body	string	нет	Уникальный номер билета. Если номер билета известен при создании платежа, ticket_number — обязательный параметр; если неизвестен, передайте booking_reference вместо ticket_number.
airline.booking_reference	body	string	нет	Номер бронирования. Обязателен, если не указан ticket_number.
airline.passengers	body	object[]	нет	Список пассажиров.
airline.legs	body	object[]	нет	Список перелетов.
transfers	body	object[]	нет	Данные о распределении денег: суммы переводов и магазины, в пользу которых они совершаются. Передаются, если вы используете Сплитование платежей.
deal	body	object	нет	Сделка, в рамках которой проводится платеж. Передается, если вы используете Безопасную сделку.
deal.id	body	string	нет	Идентификатор сделки.
deal.settlements	body	object[]	нет	Данные о распределении денег.
merchant_customer_id	body	string	нет	Идентификатор покупателя в вашей системе, например адрес электронной почты или номер телефона. Не более 200 символов. Передается, если вы хотите сохранить банковскую карту и предложить ее для автоплатежей в платежном виджете ЮKassa.
payment_order	body	object	нет	Платежное поручение — распоряжение банку на перевод для оплаты жилищно-коммунальных услуг (ЖКУ), сведения о платеже для регистрации в ГИС ЖКХ. Нужно передавать при оплате ЖКУ. Кроме обязательных параметров, должен быть передан хотя бы один из параметров: payment_document_id, payment_document_number, account_number, unified_account_number или service_id.
receiver	body	object	нет
receiver.type	body	string (mobile_balance, digital_wallet, bank_account)	нет	Код получателя платежа.
receiver.phone	body	string	нет	Номер телефона для пополнения. Максимум 15 символов. Указывается в формате ITU-T E.164. Пример: 79000000000.
receiver.account_number	body	string	нет	Идентификатор электронного кошелька для пополнения. Максимум 20 символов.
receiver.bic	body	string	нет	Банковский идентификационный код (БИК) банка, в котором открыт счет. Формат — 9 символов.
statements	body	object[]	нет	Данные для отправки выписок; обязательны, если пользователь должен получить выписку после платежа. Сейчас доступен один тип — выписка об оплате: информация об успешном платеже, которую ЮKassa отправляет на электронную почту пользователя. Отправляется, если платеж проведен банковской картой, через SberPay или СБП; доступна для всех сценариев интеграции.
pos_link	body	object	нет	Данные о кассовой ссылке для проведения платежа в офлайне.
pos_link.id	body	string	нет	Идентификатор кассовой ссылки в ЮKassa.
pos_link.expires_at	body	string	нет	Срок действия оплаты. Может составлять от 1 до 20 минут с момента создания платежа, по умолчанию 20 минут. Указывается по UTC и передается в формате ISO 8601. Пример: 2024-10-18T10:51:18.139Z

Пример запроса:

{
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "capture": true,
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.ru/return"
  },
  "description": "Оплата заказа № 72"
}

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}

GET /payments — Список платежей

Запрос позволяет получить список платежей. Можно запросить платежи, созданные за последние 3 года. Список можно отфильтровать по заданным критериям.

Документация: https://yookassa.ru/developers/api#get_payments_list

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по времени создания: время должно быть больше или равно указанного значения («от указанного момента, включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения («от указанного момента, не включая»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по времени создания: время должно быть меньше или равно указанного значения («до указанного момента, включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения («до указанного момента, не включая»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
captured_at.gte	query	string	нет	Фильтр по времени подтверждения платежа: время должно быть больше или равно указанного значения («от указанного момента, включительно»). Указывается в формате ISO 8601. Пример: captured_at.gte=2018-07-18T10:51:18.139Z
captured_at.gt	query	string	нет	Фильтр по времени подтверждения платежа: время должно быть больше указанного значения («от указанного момента, не включая»). Указывается в формате ISO 8601. Пример: captured_at.gt=2018-07-18T10:51:18.139Z
captured_at.lte	query	string	нет	Фильтр по времени подтверждения платежа: время должно быть меньше или равно указанного значения («до указанного момента, включительно»). Указывается в формате ISO 8601. Пример: captured_at.lte=2018-07-18T10:51:18.139Z
captured_at.lt	query	string	нет	Фильтр по времени подтверждения платежа: время должно быть меньше указанного значения («до указанного момента, не включая»). Указывается в формате ISO 8601. Пример: captured_at.lt=2018-07-18T10:51:18.139Z
payment_method	query	string (bank_card, cash, alfabank, webmoney, wechat, apple_pay, google_pay, qiwi)	нет	Фильтр по коду способа оплаты. Пример: payment_method=bank_card
status	query	string (pending, waiting_for_capture, succeeded, canceled)	нет	Фильтр по статусу платежа. Пример: status=succeeded
limit	query	integer	нет	Ограничение размера выдачи: количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor нужно использовать значение параметра next_cursor из ответа на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "status": "succeeded",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "created_at": "2017-11-03T11:52:31.827Z",
      "paid": true,
      "test": false,
      "refundable": true,
      "recipient": {
        "account_id": "123",
        "gateway_id": "456"
      }
    }
  ]
}

GET /payments/{payment_id} — Информация о платеже

Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_payment

Параметр	Где	Тип	Обяз.	Описание
payment_id	path	string	да	Идентификатор платежа.

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}

POST /payments/{payment_id}/capture — Подтверждение платежа

Подтверждение готовности принять платеж: статус изменится на succeeded, и можно передать пользователю товар или услугу. Подтвердить можно только платеж в статусе waiting_for_capture и только в течение ограниченного времени (зависит от способа оплаты); иначе статус изменится на canceled, а деньги вернутся пользователю.

Документация: https://yookassa.ru/developers/api#capture_payment

Параметр	Где	Тип	Обяз.	Описание
payment_id	path	string	да	Идентификатор платежа.
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
amount	body	object	нет	Итоговая сумма, которая будет списана с пользователя. Можно указать часть первоначальной суммы, чтобы вернуть остаток пользователю, если способ оплаты поддерживает частичное списание. Указывается вместе с кодом валюты, которая должна совпадать с валютой субаккаунта (recipient.gateway_id) при разделении потоков платежей или с валютой аккаунта (shopId в личном кабинете) без него.
amount.value	body	string	нет	Сумма в выбранной валюте, всегда в дробном формате. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
amount.currency	body	string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY)	нет	Трехбуквенный код валюты в формате ISO-4217. Пример: RUB.
receipt	body	object	нет	Данные для формирования чека. Параметр передается, если вы компания или индивидуальный предприниматель и используете Чеки от ЮKassa, либо используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж.
receipt.customer	body	object	нет	Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone).
receipt.items	body	object[]	нет	Список товаров в заказе. Если вы используете Чеки от ЮKassa, можно указать до 80 товаров, если стороннюю онлайн-кассу — до 100 товаров.
receipt.internet	body	boolean	нет	Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — оплата прошла онлайн (например, на вашем сайте или в приложении); false — оплата прошла офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true; если вы принимаете платежи офлайн, передайте false.
receipt.tax_system_code	body	integer	нет	Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует.
receipt.timezone	body	integer	нет	Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс.
receipt.receipt_industry_details	body	object[]	нет	Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
receipt.receipt_operational_details	body	object	нет	Операционный реквизит чека (тег в 54 ФЗ — 1270). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
airline	body	object	нет	Объект с данными для продажи авиабилетов. Используется только для платежей банковской картой.
airline.ticket_number	body	string	нет	Уникальный номер билета. Если номер билета известен при создании платежа, ticket_number обязателен. Если нет — передайте booking_reference вместо ticket_number.
airline.booking_reference	body	string	нет	Номер бронирования. Обязателен, если не передан ticket_number.
airline.passengers	body	object[]	нет	Список пассажиров.
airline.legs	body	object[]	нет	Список перелетов.
transfers	body	object[]	нет	Информация о распределении денег: суммы переводов и магазины, в пользу которых они совершаются. Передается при частичном подтверждении платежа, если вы используете Сплитование платежей.
deal	body	object	нет	Сделка, в рамках которой проводится платеж. Передается при частичном подтверждении платежа, если вы используете Безопасную сделку.
deal.settlements	body	object[]	нет	Данные о распределении денег.

Пример запроса:

{
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "receipt": {
    "items": [
      {
        "description": "string",
        "quantity": 1,
        "amount": {
          "value": null,
          "currency": null
        },
        "vat_code": 0
      }
    ]
  },
  "airline": {
    "ticket_number": "5554916004417",
    "booking_reference": "IIIKRV",
    "passengers": [
      {
        "first_name": "SERGEI",
        "last_name": "IVANOV"
      }
    ],
    "legs": [
      {
        "departure_airport": "LED",
        "destination_airport": "AMS",
        "departure_date": "2018-06-20"
      }
    ]
  },
  "transfers": [
    {
      "account_id": "123",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      }
    }
  ],
  "deal": {
    "settlements": [
      {
        "type": "payout",
        "amount": {
          "value": null,
          "currency": null
        }
      }
    ]
  }
}

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}

POST /payments/{payment_id}/cancel — Отмена платежа

Отменяет платеж в статусе waiting_for_capture. Отмена означает, что вы не готовы выдать товар или оказать услугу пользователю; после отмены деньги начнут возвращаться на счет плательщика. Если платеж был совершен банковской картой, из кошелька ЮMoney или через SberPay, деньги вернутся сразу, если другими способами — процесс может занять до нескольких дней.

Документация: https://yookassa.ru/developers/api#cancel_payment

Параметр	Где	Тип	Обяз.	Описание
payment_id	path	string	да	Идентификатор платежа.
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "succeeded",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "created_at": "2017-11-03T11:52:31.827Z",
  "paid": true,
  "test": false,
  "refundable": true,
  "recipient": {
    "account_id": "123",
    "gateway_id": "456"
  }
}

POST /refunds — Создание возврата

Создает возврат успешного платежа на указанную сумму. Платеж можно вернуть только в течение трех лет с момента его создания. Комиссия ЮKassa за проведение платежа не возвращается.

Документация: https://yookassa.ru/developers/api#create_refund

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
payment_id	body	string	да	Идентификатор платежа в ЮKassa.
amount	body	object	да	Сумма, которую нужно вернуть пользователю. Указывается вместе с кодом валюты. Должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, или с валютой аккаунта (shopId в личном кабинете), если не разделяете.
amount.value	body	string	да	Сумма в выбранной валюте, всегда в дробном формате. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
amount.currency	body	string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY)	да	Трехбуквенный код валюты в формате ISO-4217. Пример: RUB.
description	body	string	нет	Комментарий к возврату, основание для возврата денег пользователю.
receipt	body	object	нет	Данные для формирования чека. Параметр передается, если вы компания или индивидуальный предприниматель и используете Чеки от ЮKassa, либо используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж.
receipt.customer	body	object	нет	Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone).
receipt.items	body	object[]	нет	Список товаров в заказе. Если вы используете Чеки от ЮKassa, можно указать до 80 товаров, если стороннюю онлайн-кассу — до 100 товаров.
receipt.internet	body	boolean	нет	Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — оплата прошла онлайн (например, на вашем сайте или в приложении); false — оплата прошла офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true; если вы принимаете платежи офлайн, передайте false.
receipt.tax_system_code	body	integer	нет	Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует.
receipt.timezone	body	integer	нет	Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс.
receipt.receipt_industry_details	body	object[]	нет	Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
receipt.receipt_operational_details	body	object	нет	Операционный реквизит чека (тег в 54 ФЗ — 1270). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
sources	body	object[]	нет	Данные о том, с какого магазина и какую сумму нужно удержать для проведения возврата. Необходимо передавать, если вы используете Сплитование платежей. Сейчас в этом параметре можно передать данные только одного магазина.
deal	body	object	нет	Данные о сделке, в составе которой проходит возврат. Необходимо передавать, если вы проводите Безопасную сделку.
deal.refund_settlements	body	object[]	нет	Данные о распределении денег.
refund_method_data	body	object	нет	Данные для возврата платежа по электронному сертификату.
refund_method_data.type	body	string (sbp, electronic_certificate)	нет	Код способа оплаты, который использовался при проведении платежа.
refund_method_data.electronic_certificate	body	object	нет	Данные от ФЭС НСПК для возврата на электронный сертификат. Неоходимо передавать только при оплате со сбором данных на вашей стороне.
refund_method_data.articles	body	object[]	нет	Корзина возврата (в терминах НСПК) — список возвращаемых товаров, для оплаты которых использовался электронный сертификат. Данные должны соответствовать товарам из одобренной корзины покупки (articles в объекте платежа: https://yookassa.ru/developers/api#payment_object). Необходимо передавать только при оплате на готовой странице ЮKassa.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, не более 32 символов в названии ключа, не более 512 символов в значении ключа, тип данных — строка в формате UTF-8.

Пример запроса:

{
  "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  }
}

Пример ответа:

{
  "id": "1ddd77af-0bd7-500d-895b-c475c55fdefc",
  "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "created_at": "2017-11-03T11:52:31.827Z"
}

GET /refunds — Список возвратов

Возвращает список возвратов. Доступны возвраты, созданные за последние 3 года. Список можно фильтровать по заданным критериям.

Документация: https://yookassa.ru/developers/api#get_refunds_list

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения или равно ему («от момента, включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения («от момента, не включая его»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («до момента, включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения («до момента, не включая его»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
payment_id	query	string	нет	Фильтр по идентификатору платежа (получить все возвраты по платежу). Пример: payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9
status	query	string (pending, succeeded, canceled)	нет	Фильтр по статусу возврата. Возможные значения: pending — в обработке, succeeded — успешно выполнен, canceled — отменен. Пример: status=succeeded
limit	query	integer	нет	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10.
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor нужно использовать значение параметра next_cursor из ответа на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "1ddd77af-0bd7-500d-895b-c475c55fdefc",
      "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "status": "succeeded",
      "created_at": "2017-11-03T11:52:31.827Z"
    }
  ]
}

GET /refunds/{refund_id} — Информация о возврате

Запрос позволяет получить информацию о текущем состоянии возврата по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_refund

Параметр	Где	Тип	Обяз.	Описание
refund_id	path	string	да	Идентификатор возврата.

Пример ответа:

{
  "id": "1ddd77af-0bd7-500d-895b-c475c55fdefc",
  "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "created_at": "2017-11-03T11:52:31.827Z"
}

POST /receipts — Создание чека

Используйте этот запрос при оплате с соблюдением требований 54-ФЗ, чтобы создать чек зачета предоплаты. Если вы работаете по сценарию «Сначала платеж, потом чек», в запросе также нужно передавать данные для формирования чека прихода и чека возврата прихода.

Документация: https://yookassa.ru/developers/api#create_receipt

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
type	body	string (payment, refund)	да	Тип чека в онлайн-кассе. Возможные значения: payment (приход), refund (возврат прихода).
payment_id	body	string	нет	Идентификатор платежа в ЮKassa для отображения информации о чеке в личном кабинете; на платеж не влияет. Обязателен при создании чека платежа (тип чека: payment, статус платежа: waiting_for_capture или succeeded) и чека возврата для отмененных или частично подтвержденных платежей (тип чека: refund, статус платежа: canceled или succeeded). Для одного платежа можно создать до 50 чеков.
refund_id	body	string	нет	Идентификатор возврата в ЮKassa для отображения информации о чеке в личном кабинете. Обязателен при создании чека возврата (тип чека: refund, статус платежа: succeeded). Для одного возврата можно создать до 50 чеков.
customer	body	object	да	Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone).
customer.full_name	body	string	нет	Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов. Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу Orange Data, Атол Онлайн.
customer.inn	body	string	нет	ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре full_name. Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу Orange Data, Атол Онлайн.
customer.email	body	string	нет	Адрес электронной почты пользователя для отправки чека. Обязательный параметр, если вы используете Чеки от ЮKassa или стороннюю онлайн-кассу и не передаете параметр phone.
customer.phone	body	string	нет	Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например 79000000000. Обязательный параметр, если не передан email.
items	body	object[]	да	Список товаров в чеке: не более 80 позиций для Чеков от ЮKassa, не более 100 позиций для сторонних онлайн-касс.
internet	body	boolean	нет	Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — оплата прошла онлайн, через интернет (например, на вашем сайте или в приложении); false — оплата прошла офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true; если вы принимаете платежи офлайн, передайте в запросе значение false.
send	body	boolean	да	Формирование чека в онлайн-кассе сразу после создания объекта чека. Сейчас можно передать только значение true.
tax_system_code	body	integer	нет	Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует.
timezone	body	integer	нет	Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс.
additional_user_props	body	object	нет	Дополнительный реквизит пользователя (тег в 54 ФЗ — 1084). Можно передавать, если вы отправляете данные для формирования чека по сценарию Сначала платеж, потом чек
additional_user_props.name	body	string	нет	Наименование дополнительного реквизита пользователя (тег в 54 ФЗ — 1085). Не более 64 символов.
additional_user_props.value	body	string	нет	Значение дополнительного реквизита пользователя (тег в 54 ФЗ — 1086). Не более 234 символов.
receipt_industry_details	body	object[]	нет	Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Нужно передавать, если используете ФФД 1.2.
receipt_operational_details	body	object	нет	Операционный реквизит чека (тег в 54 ФЗ — 1270). Нужно передавать, если используете ФФД 1.2.
receipt_operational_details.operation_id	body	integer	нет	Идентификатор операции (тег в 54 ФЗ — 1271). Число от 0 до 255.
receipt_operational_details.value	body	string	нет	Данные операции (тег в 54 ФЗ — 1272).
receipt_operational_details.created_at	body	string	нет	Время создания операции (тег в 54 ФЗ — 1273). Указывается по UTC и передается в формате ISO 8601. Пример: 2017-11-03T11:52:31.827Z
settlements	body	object[]	да	Перечень совершенных расчетов.
on_behalf_of	body	string	нет	Идентификатор магазина, от имени которого нужно отправить чек. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId). Необходимо передавать, если вы используете Сплитование платежей.

Пример запроса:

{
  "customer": {
    "full_name": "Иванов Иван Иванович",
    "inn": "6321341814",
    "email": "user@yoomoney.ru",
    "phone": "79000000000"
  },
  "type": "payment",
  "send": true,
  "settlements": [
    {
      "type": "cashless",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      }
    }
  ],
  "items": [
    {
      "description": "string",
      "quantity": 1,
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "vat_code": 0
    }
  ]
}

Пример ответа:

{
  "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "status": "succeeded",
  "items": [
    {
      "description": "string",
      "quantity": 1,
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "vat_code": 0
    }
  ]
}

GET /receipts — Список чеков

Запрос позволяет получить список чеков, отфильтрованный по заданным критериям. Можно запросить чеки по конкретному платежу, чеки по конкретному возврату или все чеки магазина.

Документация: https://yookassa.ru/developers/api#get_receipts_list

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («до такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения («до такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
status	query	string (pending, succeeded, canceled)	нет	Фильтр по статусу чека. Возможные значения: pending — в обработке, succeeded — успешно зарегистрирован, canceled — отменен. Пример: status=succeeded
payment_id	query	string	нет	Фильтр по идентификатору платежа (получить все чеки для указанного платежа). Пример: payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9 В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата.
refund_id	query	string	нет	Фильтр по идентификатору возврата (получить все чеки для указанного возврата). Пример: refund_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9 В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата.
limit	query	integer	нет	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor необходимо использовать значение параметра next_cursor, полученное в ответе на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "type": "payment",
      "status": "succeeded",
      "items": [
        {
          "description": null,
          "quantity": null,
          "amount": null,
          "vat_code": null
        }
      ]
    }
  ]
}

GET /receipts/{receipt_id} — Информация о чеке

Запрос позволяет получить информацию о текущем состоянии чека по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_receipt

Параметр	Где	Тип	Обяз.	Описание
receipt_id	path	string	да	Идентификатор чека.

Пример ответа:

{
  "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "status": "succeeded",
  "items": [
    {
      "description": "string",
      "quantity": 1,
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "vat_code": 0
    }
  ]
}

GET /me — Информация о настройках магазина или шлюза

С помощью этого запроса можно получить информацию о магазине или шлюзе. Для Сплитования платежей в запросе нужно передать параметр on_behalf_of с идентификатором магазина продавца и ваши данные для аутентификации (идентификатор и секретный ключ вашей платформы). Для партнеров нужно передать OAuth-токен магазина. Для выплат нужно передать ваши данные для аутентификации (идентификатор и секретный ключ вашего шлюза).

Документация: https://yookassa.ru/developers/api#get_me

Параметр	Где	Тип	Обяз.	Описание
on_behalf_of	query	string	нет	Только для тех, кто использует Сплитование платежей. Идентификатор магазина продавца, подключенного к вашей платформе, информацию о котором нужно получить.

Пример ответа:

{
  "account_id": "123",
  "test": true,
  "status": "enabled"
}

POST /webhooks — Создание webhook

С помощью этого запроса можно подписаться на уведомления о событии (например, об изменении статуса платежа на succeeded). Через вебхуки можно подписаться только на события платежей и возвратов; чтобы получать уведомления о нескольких событиях, нужно создать отдельный вебхук для каждого из них. Для каждого OAuth-токена нужен свой набор вебхуков.

Документация: https://yookassa.ru/developers/api#create_webhook

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
event	body	string (payment.waiting_for_capture, payment.succeeded, payment.canceled, refund.succeeded, payment_method.active)	да	Событие, которое вы хотите отслеживать.
url	body	string	да	URL, на который ЮKassa будет отправлять уведомления.

Пример запроса:

{
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}

Пример ответа:

{
  "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.example.com/notification_url"
}

GET /webhooks — Список созданных webhook

С помощью этого запроса можно проверить, какие вебхуки доступны для переданного OAuth-токена.

Документация: https://yookassa.ru/developers/api#get_webhook_list

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "wh-e44e8088-bd73-43b1-959a-954f3a7d0c54",
      "event": "payment.succeeded",
      "url": "https://www.example.com/notification_url"
    }
  ]
}

DELETE /webhooks/{webhook_id} — Удаление webhook

С помощью этого запроса можно отписаться от уведомлений о событиях для переданного OAuth-токена. Чтобы удалить вебхук, укажите его идентификатор в запросе.

Документация: https://yookassa.ru/developers/api#delete_webhook

Параметр	Где	Тип	Обяз.	Описание
webhook_id	path	string	да	Идентификатор webhook-a.

Пример ответа:

{}

POST /payment_methods — Создание способа оплаты

Создает в ЮKassa объект способа оплаты. В запросе передайте код способа оплаты, который хотите сохранить, и при необходимости дополнительные параметры нужной функциональности. Идентификатор созданного способа оплаты можно использовать при проведении автоплатежей или выплат.

Документация: https://yookassa.ru/developers/api#create_payment_method

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
type	body	string (bank_card, sbp)	да
holder	body	object	нет	Данные магазина, для которого сохраняется способ оплаты.
holder.gateway_id	body	string	нет	Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
client_ip	body	string	нет	IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-соединения.
confirmation	body	object	нет
confirmation.type	body	string (redirect, qr)	нет	Код сценария подтверждения пользователем привязки платежного средства к вашему магазину в ЮKassa.
confirmation.enforce	body	boolean	нет	Запрос на проведение привязки с аутентификацией по 3-D Secure. Сработает, если вы по умолчанию принимаете оплату банковской картой без подтверждения платежа пользователем; в остальных случаях аутентификацией по 3-D Secure управляет ЮKassa. Чтобы принимать платежи и создавать привязки без дополнительного подтверждения пользователем, напишите вашему менеджеру ЮKassa.
confirmation.return_url	body	string	нет	URL, на который вернется пользователь после подтверждения или отмены привязки на веб-странице. Не более 2048 символов.
confirmation.locale	body	string (ru_RU, en_US)	нет	Язык интерфейса, писем и смс, которые будут показаны или отправлены пользователю. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8.
card	body	object	нет	Данные банковской карты (необходимы, если вы собираете данные карты пользователей на своей стороне).
card.number	body	string	нет	Номер банковской карты.
card.expiry_year	body	string	нет	Срок действия, год, YYYY.
card.expiry_month	body	string	нет	Срок действия, месяц, MM.
card.cardholder	body	string	нет	Имя владельца карты.
card.csc	body	string	нет	Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне карты.

Пример запроса:

{
  "type": "bank_card"
}

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "bank_card",
  "saved": true,
  "status": "active",
  "holder": {
    "account_id": "123"
  }
}

GET /payment_methods/{payment_method_id} — Информация о способе оплаты

Используйте этот запрос, чтобы получить информацию о текущем состоянии способа оплаты по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_payment_method

Параметр	Где	Тип	Обяз.	Описание
payment_method_id	path	string	да	Идентификатор сохраненного способа оплаты.

Пример ответа:

{
  "id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "bank_card",
  "saved": true,
  "status": "active",
  "holder": {
    "account_id": "123"
  }
}

POST /invoices — Создание счета

Создает в ЮKassa объект счета. В запросе передайте данные о заказе, которые отобразятся на странице счета, и данные для проведения платежа.

Документация: https://yookassa.ru/developers/api#create_invoice

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
payment_data	body	object	да	Данные для проведения платежа по выставленному счету.
payment_data.amount	body	object	да	Сумма платежа. Должна быть в пределах лимитов. Указывается вместе с кодом валюты. Должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, или с валютой аккаунта (shopId в личном кабинете), если не разделяете.
payment_data.receipt	body	object	нет	Данные для формирования чека. Параметр передается, если вы компания или индивидуальный предприниматель и используете Чеки от ЮKassa, либо используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж.
payment_data.recipient	body	object	нет	Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.
payment_data.save_payment_method	body	boolean	нет	Сохранение платежных данных для проведения автоплатежей. Возможные значения: * true — сохранить способ оплаты (сохранить платежные данные); * false — провести платеж без сохранения способа оплаты. Доступно только после согласования с менеджером ЮKassa.
payment_data.capture	body	boolean	нет	Автоматический прием поступившего платежа. Возможные значения: * true — оплата списывается сразу (платеж в одну стадию); * false — оплата холдируется и списывается по вашему запросу (платеж в две стадии: https://yookassa.ru/developers/payment-acceptance/getting-started/payment-process#capture-and-cancel). По умолчанию false.
payment_data.client_ip	body	string	нет	IPv4- или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-соединения.
payment_data.description	body	string	нет	Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru».
payment_data.metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8.
cart	body	object[]	да	Корзина заказа — список товаров или услуг, который отобразится на странице счета перед оплатой.
delivery_method_data	body	object	нет
delivery_method_data.type	body	string (self, sms, email)	нет	Код способа доставки счета.
delivery_method_data.phone	body	string	нет	Номер телефона, на который ЮKassa отправит смс со ссылкой на счет. Указывается в формате ITU-T E.164, например 79000000000.
delivery_method_data.email	body	string	нет	Адрес электронной почты, на который ЮKassa отправит письмо со ссылкой на счет.
expires_at	body	string	да	Срок действия счета — дата и время, до которых можно оплатить выставленный счет. Указывается по UTC и передается в формате ISO 8601. Пример: 2024-10-18T10:51:18.139Z
locale	body	string (ru_RU, en_US)	нет	Язык интерфейса, писем и смс, которые будут показаны или отправлены пользователю. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US. Регистр важен.
description	body	string	нет	Описание выставленного счета (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь на странице счета. Например: «Счет на оплату по договору 37».
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ — значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, имя ключа — не более 32 символов, значение ключа — не более 512 символов, тип данных — строка в формате UTF-8.

Пример запроса:

{
  "payment_data": {
    "amount": {
      "value": "1000.00",
      "currency": "RUB"
    }
  },
  "cart": [
    {
      "description": "string",
      "price": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "quantity": 1
    }
  ],
  "expires_at": "2024-10-18T10:51:18.139Z"
}

Пример ответа:

{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "succeeded",
  "cart": [
    {
      "description": "string",
      "price": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "quantity": 1
    }
  ],
  "created_at": "2017-11-03T11:52:31.827Z"
}

GET /invoices/{invoice_id} — Информация о счете

Используйте этот запрос, чтобы получить информацию о текущем состоянии счета по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_invoice

Параметр	Где	Тип	Обяз.	Описание
invoice_id	path	string	да	Идентификатор счета в ЮKassa.

Пример ответа:

{
  "id": "in-e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "status": "succeeded",
  "cart": [
    {
      "description": "string",
      "price": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "quantity": 1
    }
  ],
  "created_at": "2017-11-03T11:52:31.827Z"
}

POST /deals — Создание сделки

Отправьте запрос, чтобы создать сделку, в рамках которой нужно принять платеж от покупателя и перевести его продавцу.

Документация: https://yookassa.ru/developers/api#create_deal

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
type	body	string (safe_deal)	да	Тип сделки. Фиксированное значение: safe_deal — Безопасная сделка.
fee_moment	body	string (payment_succeeded, deal_closed)	да	Момент, когда вам зачисляется вознаграждение маркетплейса. Возможные значения: payment_succeeded — после успешной оплаты; deal_closed — после закрытия сделки по итогам успешной выплаты.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, не более 32 символов в названии ключа, не более 512 символов в значении ключа, тип данных — строка в формате UTF-8.
description	body	string	нет	Описание сделки (не более 128 символов). Используется для фильтрации при получении списка сделок.

Пример запроса:

{
  "type": "safe_deal",
  "fee_moment": "payment_succeeded"
}

Пример ответа:

{
  "type": "safe_deal",
  "id": "dl-d68d2fe4-2abb-47e5-8112-32e28f87fb52",
  "balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "closed",
  "created_at": "2020-07-03T11:52:31.827Z",
  "expires_at": "2021-01-03T18:31:22.532Z",
  "test": false,
  "fee_moment": "payment_succeeded"
}

GET /deals — Список сделок

Запрос позволяет получить список сделок, отфильтрованный по заданным критериям.

Документация: https://yookassa.ru/developers/api#get_deals_list

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («до такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения («до такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
expires_at.gte	query	string	нет	Фильтр по времени автоматического закрытия сделки: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: expires_at.gte=2018-07-18T10:51:18.139Z
expires_at.gt	query	string	нет	Фильтр по времени автоматического закрытия сделки: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: expires_at.gt=2018-07-18T10:51:18.139Z
expires_at.lte	query	string	нет	Фильтр по времени автоматического закрытия сделки: время должно быть меньше указанного значения или равно ему («до такого-то момента включительно»). Указывается в формате ISO 8601. Пример: expires_at.lte=2018-07-18T10:51:18.139Z
expires_at.lt	query	string	нет	Фильтр по времени автоматического закрытия сделки: время должно быть меньше указанного значения («до такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: expires_at.lt=2018-07-18T10:51:18.139Z
status	query	string (opened, closed)	нет	Фильтр по статусу сделки. Пример: status=closed
full_text_search	query	string	нет	Фильтр по описанию сделки в параметре description (например, по идентификатору сделки на стороне вашего маркетплейса в ЮKassa либо по идентификатору покупателя или продавца). От 4 до 128 символов. Пример: 123554642-2432FF344R
limit	query	integer	нет	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor необходимо использовать значение параметра next_cursor, полученное в ответе на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "type": "safe_deal",
      "id": "dl-d68d2fe4-2abb-47e5-8112-32e28f87fb52",
      "balance": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "payout_balance": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "status": "closed",
      "created_at": "2020-07-03T11:52:31.827Z",
      "expires_at": "2021-01-03T18:31:22.532Z",
      "test": false,
      "fee_moment": "payment_succeeded"
    }
  ]
}

GET /deals/{deal_id} — Информация о сделке

Запрос позволяет получить информацию о текущем состоянии сделки по ее уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_deal

Параметр	Где	Тип	Обяз.	Описание
deal_id	path	string	да	Идентификатор сделки.

Пример ответа:

{
  "type": "safe_deal",
  "id": "dl-d68d2fe4-2abb-47e5-8112-32e28f87fb52",
  "balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "payout_balance": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "closed",
  "created_at": "2020-07-03T11:52:31.827Z",
  "expires_at": "2021-01-03T18:31:22.532Z",
  "test": false,
  "fee_moment": "payment_succeeded"
}

POST /payouts — Создание выплаты

Используйте этот запрос, чтобы создать в ЮKassa объект выплаты. В запросе нужно передать сумму выплаты, данные о способе получения выплаты (например, номер кошелька ЮMoney), описание выплаты и при необходимости дополнительные параметры. Параметры и данные для аутентификации зависят от платежного решения — обычные выплаты или выплаты в рамках Безопасной сделки.

Документация: https://yookassa.ru/developers/api#create_payout

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
amount	body	object	да	Сумма выплаты. Есть ограничения на минимальный и максимальный размер выплаты и сумму выплат за месяц. Подробнее о лимитах обычных выплат и выплат в рамках Безопасной сделки
amount.value	body	string	да	Сумма в выбранной валюте, всегда в дробном виде. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
amount.currency	body	string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY)	да	Трехбуквенный код валюты в формате ISO-4217. Пример: RUB.
payout_destination_data	body	object	нет
payout_destination_data.type	body	string (yoo_money, bank_card, sbp)	нет	Способ получения выплаты: * yoo_money — выплаты на кошелек ЮMoney; * bank_card — выплаты на банковскую карту; * sbp — выплаты через СБП на счет в банке или платежном сервисе.
payout_destination_data.account_number	body	string	нет	Номер кошелька ЮMoney, например 41001614575714. Длина от 11 до 33 цифр. Статус кошелька для обычных выплат — любой, для выплат в рамках Безопасной сделки — именной или идентифицированный.
payout_destination_data.card	body	object	нет	Данные банковской карты для выплаты.
payout_destination_data.phone	body	string	нет	Телефон, к которому привязан счет получателя выплаты в системе участника СБП. Указывается в формате ITU-T E.164, например 79000000000.
payout_destination_data.bank_id	body	string	нет	Идентификатор участника СБП — банка или платежного сервиса, подключенного к сервису. Максимум 12 символов.
payout_token	body	string	нет	Токенизированные данные для выплаты. Например, синоним банковской карты. Обязательный параметр, если не передан payout_destination_data или payment_method_id.
payment_method_id	body	string	нет	Идентификатор сохраненного способа оплаты, данные которого нужно использовать для проведения выплаты. Подробнее о выплатах с использованием идентификатора сохраненного способа оплаты Обязательный параметр, если не передан payout_destination_data или payout_token.
description	body	string	нет	Описание транзакции (не более 128 символов). Например: «Выплата по договору 37».
deal	body	object	нет	Сделка, в рамках которой нужно провести выплату. Необходимо передавать, если вы проводите Безопасную сделку
deal.id	body	string	нет	Идентификатор сделки.
personal_data	body	object[]	нет	Персональные данные получателя выплаты. Только для обычных выплат. Необходимо передавать в этих сценариях: * выплаты с проверкой получателя (только для выплат через СБП); * выплаты с передачей данных получателя для выписок из реестра. В массиве можно одновременно передать несколько идентификаторов, но только для разных типов данных.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не больше 16 ключей, имя ключа — не больше 32 символов, значение ключа — не больше 512 символов, тип данных — строка в формате UTF-8.

Пример запроса:

{
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  }
}

Пример ответа:

{
  "id": "po-27ced252-0025-5000-9000-0a682a8bab8f",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card"
  },
  "created_at": "2020-07-03T11:52:31.827Z",
  "test": false
}

GET /payouts — Список выплат

Используйте этот запрос, чтобы получить список выплат. Доступны выплаты, созданные за последние 3 года. Список можно отфильтровать по заданным критериям. Способ аутентификации запроса зависит от решения, которое вы используете: обычные выплаты или выплаты в рамках Безопасной сделки.

Документация: https://yookassa.ru/developers/api#get_payouts_list

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по времени создания: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («до такого-то момента включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по времени создания: время должно быть меньше указанного значения («до такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
succeeded_at.gte	query	string	нет	Фильтр по времени успешной обработки выплаты: время должно быть больше указанного значения или равно ему («от такого-то момента включительно»). Указывается в формате ISO 8601. Пример: succeeded_at.gte=2018-07-18T10:51:18.139Z
succeeded_at.gt	query	string	нет	Фильтр по времени успешной обработки выплаты: время должно быть больше указанного значения («от такого-то момента не включительно»). Указывается в формате ISO 8601. Пример: succeeded_at.gt=2018-07-18T10:51:18.139Z
succeeded_at.lte	query	string	нет	Фильтр по времени успешного проведения выплаты: время должно быть меньше указанного значения или равно ему («до момента времени включительно»). Указывается в формате ISO 8601. Пример: succeeded_at.lte=2018-07-18T10:51:18.139Z
succeeded_at.lt	query	string	нет	Фильтр по времени успешного проведения выплаты: время должно быть меньше указанного значения («до момента времени исключительно»). Указывается в формате ISO 8601. Пример: succeeded_at.lt=2018-07-18T10:51:18.139Z
payout_destination.type	query	string (yoo_money, bank_card, sbp)	нет	Фильтр по способу получения выплаты. Пример: payout_destination.type=bank_card
status	query	string (pending, succeeded, canceled)	нет	Фильтр по статусу выплаты. Пример: status=succeeded
limit	query	integer	нет	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10.
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor необходимо использовать параметр next_cursor, полученный в ответе на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "po-27ced252-0025-5000-9000-0a682a8bab8f",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "status": "pending",
      "payout_destination": {
        "type": "bank_card"
      },
      "created_at": "2020-07-03T11:52:31.827Z",
      "test": false
    }
  ]
}

GET /payouts/search — Поиск выплат

Используйте этот запрос, чтобы найти выплаты по заданным критериям. Доступен только для выплат, созданных за последние 3 месяца; сейчас поддерживается поиск только по параметру metadata, а также можно указать дату и время создания выплаты (параметр created_at). Данные для аутентификации запросов зависят от платежного решения — обычные выплаты или выплаты в рамках Безопасной сделки.

Документация: https://yookassa.ru/developers/api#get_payouts_search

Параметр	Где	Тип	Обяз.	Описание
created_at.gte	query	string	нет	Фильтр по дате создания: время должно быть больше указанного значения или равно ему («от момента времени включительно»). Указывается в формате ISO 8601. Пример: created_at.gte=2018-07-18T10:51:18.139Z
created_at.gt	query	string	нет	Фильтр по дате создания: время должно быть больше указанного значения («от момента времени исключительно»). Указывается в формате ISO 8601. Пример: created_at.gt=2018-07-18T10:51:18.139Z
created_at.lte	query	string	нет	Фильтр по дате создания: время должно быть меньше указанного значения или равно ему («до момента времени включительно»). Указывается в формате ISO 8601. Пример: created_at.lte=2018-07-18T10:51:18.139Z
created_at.lt	query	string	нет	Фильтр по дате создания: время должно быть меньше указанного значения («до момента времени исключительно»). Указывается в формате ISO 8601. Пример: created_at.lt=2018-07-18T10:51:18.139Z
metadata	query	object	нет	Фильтр по объекту metadata: строгий поиск по паре «ключ-значение» (возвращаются объекты с точным совпадением ключа и значения). Ограничения: не больше одной пары «ключ-значение», имя ключа — не больше 32 символов, значение ключа — не больше 512 символов, тип данных — строка в формате UTF-8 в URL-кодированном виде. Шаблон: metadata[key]=value. Пример: metadata%5Boperation_id%5D=e2ab2e1c-776d-4376-aba8-d2099243d1f6
limit	query	integer	нет	Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример: limit=50. Значение по умолчанию: 10.
cursor	query	string	нет	Указатель на следующий фрагмент списка. Пример: cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15. В качестве cursor необходимо использовать параметр next_cursor, полученный в ответе на предыдущий запрос. Используется, если размер списка больше размера выдачи (limit) и конец выдачи не достигнут.

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "id": "po-27ced252-0025-5000-9000-0a682a8bab8f",
      "amount": {
        "value": "1000.00",
        "currency": "RUB"
      },
      "status": "pending",
      "payout_destination": {
        "type": "bank_card"
      },
      "created_at": "2020-07-03T11:52:31.827Z",
      "test": false
    }
  ]
}

GET /payouts/{payout_id} — Информация о выплате

Используйте этот запрос, чтобы получить информацию о текущем состоянии выплаты по ее уникальному идентификатору. Данные для аутентификации запросов зависят от платежного решения — обычные выплаты или выплаты в рамках Безопасной сделки.

Документация: https://yookassa.ru/developers/api#get_payout

Параметр	Где	Тип	Обяз.	Описание
payout_id	path	string	да	Идентификатор выплаты.

Пример ответа:

{
  "id": "po-27ced252-0025-5000-9000-0a682a8bab8f",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "pending",
  "payout_destination": {
    "type": "bank_card"
  },
  "created_at": "2020-07-03T11:52:31.827Z",
  "test": false
}

GET /sbp_banks — Список участников СБП

С помощью этого запроса можно получить актуальный список всех участников СБП. Список необходимо показать получателю выплаты, а идентификатор выбранного участника СБП — передать в запросе на создание выплаты.

Документация: https://yookassa.ru/developers/api#get_sbp_banks_list

Пример ответа:

{
  "type": "list",
  "items": [
    {
      "bank_id": "100000000111",
      "name": "Сбербанк",
      "bic": "044525225"
    }
  ]
}

POST /personal_data — Создание персональных данных

Используйте этот запрос, чтобы создать в ЮKassa объект персональных данных. Укажите тип данных (цель, для которой они будут использоваться) и информацию о пользователе: имя, фамилию, отчество и другие данные в зависимости от выбранного типа. Идентификатор созданного объекта персональных данных используйте в запросе на создание выплаты.

Документация: https://yookassa.ru/developers/api#create_personal_data

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
type	body	string (payout_statement_recipient, sbp_payout_recipient)	да	Тип персональных данных — цель, для которой вы будете использовать данные. Возможные значения: sbp_payout_recipient — выплаты с проверкой получателя (только для выплат через СБП); payout_statement_recipient — выплаты с данными получателя для выписок из отчета о выплатах.
metadata	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не больше 16 ключей, имя ключа — не больше 32 символов, значение ключа — не больше 512 символов, тип данных — строка в формате UTF-8.
last_name	body	string	да	Фамилия пользователя.
first_name	body	string	да	Имя пользователя.
middle_name	body	string	нет	Отчество пользователя. Обязательный параметр, если указано в паспорте.
birthdate	body	string	нет	Дата рождения. Указывается в формате ISO 8601.

Пример запроса:

{
  "type": "sbp_payout_recipient",
  "last_name": "Иванов",
  "first_name": "Иван"
}

Пример ответа:

{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "type": "sbp_payout_recipient",
  "created_at": "string"
}

GET /personal_data/{personal_data_id} — Информация о персональных данных

С помощью этого запроса можно получить информацию о текущем статусе объекта персональных данных по его уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_personal_data

Параметр	Где	Тип	Обяз.	Описание
personal_data_id	path	string	да	Идентификатор персональных данных, сохраненных в ЮKassa.

Пример ответа:

{
  "id": "pd-22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_operation",
  "type": "sbp_payout_recipient",
  "created_at": "string"
}

POST /pos_links — Активация кассовой ссылки

Используйте этот запрос, чтобы создать в ЮKassa объект кассовой ссылки и активировать кассовую ссылку для последующего приема платежей по платежным табличкам. В запросе необходимо передать кассовую ссылку и идентификатор торговой точки.

Документация: https://yookassa.ru/developers/api#create_pos_link

Параметр	Где	Тип	Обяз.	Описание
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
recipient	body	object	да	Идентификатор торговой точки. Например, конкретной кассы в вашем магазине. Вы получите идентификатор от менеджера ЮKassa при подключении платежей.
recipient.gateway_id	body	string	да	Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
pos_link_data	body	object	да	Данные кассовой ссылки — уникальной ссылки, зашифрованной в QR-коде и NFC-метке на платежной табличке.
pos_link_data.link	body	string	да	Кассовая ссылка с платежной таблички. Чтобы получить ее, отсканируйте QR-код на табличке.

Пример запроса:

{
  "recipient": {
    "gateway_id": "456"
  },
  "pos_link_data": {
    "link": "https://qr.nspk.ru/AD100003N2S98C2U48D6N60M12345678"
  }
}

Пример ответа:

{
  "id": "pl-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "active",
  "type": "nspk",
  "recipient": {
    "gateway_id": "456"
  }
}

GET /pos_links/{pos_link_id} — Информация о кассовой ссылке

Используйте этот запрос, чтобы получить информацию о текущем состоянии кассовой ссылки по ее уникальному идентификатору.

Документация: https://yookassa.ru/developers/api#get_pos_link

Параметр	Где	Тип	Обяз.	Описание
pos_link_id	path	string	да	Идентификатор кассовой ссылки в ЮKassa.

Пример ответа:

{
  "id": "pl-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "active",
  "type": "nspk",
  "recipient": {
    "gateway_id": "456"
  }
}

POST /pos_links/{pos_link_id}/recipient — Изменение торговой точки, привязанной к кассовой ссылке

Используйте этот запрос, чтобы привязать к кассовой ссылке другую торговую точку. В запросе необходимо передать идентификатор торговой точки, которую вы хотите привязать к кассовой ссылке. После привязки кассовой ссылки перенесите платежную табличку на новую торговую точку (например, если привязали к ссылке новую кассу, переместите табличку туда).

Документация: https://yookassa.ru/developers/api#recipient_pos_link

Параметр	Где	Тип	Обяз.	Описание
pos_link_id	path	string	да	Идентификатор кассовой ссылки в ЮKassa.
Idempotence-Key	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
recipient	body	object	да	Идентификатор торговой точки, которую вы хотите привязать к кассовой ссылке.
recipient.gateway_id	body	string	да	Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.

Пример запроса:

{
  "recipient": {
    "gateway_id": "456"
  }
}

Пример ответа:

{
  "id": "pl-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "active",
  "type": "nspk",
  "recipient": {
    "gateway_id": "456"
  }
}

POST /pos_links/{pos_link_id}/deactivate — Деактивация кассовой ссылки

Используйте этот запрос, чтобы деактивировать кассовую ссылку и приостановить прием платежей по этой платежной табличке. В запросе передайте идентификатор кассовой ссылки, которую хотите деактивировать. При необходимости вы можете активировать ранее деактивированную кассовую ссылку.

Документация: https://yookassa.ru/developers/api#deactivate_pos_link

Параметр	Где	Тип	Обяз.	Описание
pos_link_id	path	string	да	Идентификатор кассовой ссылки в ЮKassa.

Пример ответа:

{
  "id": "pl-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "active",
  "type": "nspk",
  "recipient": {
    "gateway_id": "456"
  }
}

POST /pos_links/{pos_link_id}/activate — Активация ранее деактивированной кассовой ссылки

Используйте этот запрос, чтобы активировать ранее деактивированную кассовую ссылку и возобновить прием платежей по этой платежной табличке. В запросе передайте идентификатор кассовой ссылки, которую вы ранее деактивировали.

Документация: https://yookassa.ru/developers/api#activate_pos_link

Параметр	Где	Тип	Обяз.	Описание
pos_link_id	path	string	да	Идентификатор кассовой ссылки в ЮKassa.

Пример ответа:

{
  "id": "pl-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "status": "active",
  "type": "nspk",
  "recipient": {
    "gateway_id": "456"
  }
}

Нюансы

• capture по умолчанию false: без capture: true платеж останется в статусе waiting_for_capture и в момент expires_at отменится автоматически, деньги вернутся покупателю.
• Для POST и DELETE обязателен заголовок Idempotence-Key — до 64 символов, рекомендуется UUID. Повтор с тем же ключом в течение 24 часов вернет результат первого запроса; для новой операции нужен новый ключ.
• HTTP 500 не значит, что операция не прошла: результат неизвестен. Повтори запрос с теми же данными и тем же ключом идемпотентности или запроси объект через GET.
• Возврат покупателя на return_url не означает успешную оплату — статус проверяй на сервере или по HTTP-уведомлению.
• Сумма — строка с точкой и двумя знаками: "1000.00", вместе с кодом валюты.
• Методы /webhooks работают только с OAuth-токеном в партнерской программе. Обычный магазин настраивает уведомления в личном кабинете.
• Вернуть платеж можно в течение трех лет с момента создания. Комиссия ЮKassa за платеж не возвращается.
• Для Чеков от ЮKassa частичная предоплата, аванс и кредит не поддерживаются.

Примеры кода

Запрос с использованием OAuth-токена (партнерская программа)

curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth-токен>"

Ответ с ошибкой

{
  "type" : "error",
  "id" : "55a02ced-be5d-462d-a6fb-0ace18881671",
  "code" : "invalid_request",
  "description" : "Idempotence key is too long. Send the value in accordance with the documentation",
  "parameter" : "Idempotence-Key"
}

Ошибки

Код	Описание
400	invalid_request — ошибка в параметрах или логике запроса, проблемы с ключом идемпотентности. Причина — в description и parameter. Исправь запрос и повтори с новым ключом идемпотентности.
401	invalid_credentials — нет заголовка Authorization, неверный идентификатор или секретный ключ, устаревший или отозванный OAuth-токен.
403	forbidden — не хватает прав: функцию нужно согласовать с менеджером ЮKassa или для OAuth не запрошены нужные права.
404	not_found — объект не найден: создан в другом магазине или в идентификаторе опечатка.
405	Неверный HTTP-метод, например GET вместо POST для отмены платежа. Поддерживаемый метод — в заголовке Allow.
415	Неверный тип контента: тело POST-запроса должно быть в JSON.
429	too_many_requests — слишком много запросов. Увеличь интервалы между запросами.
500	internal_server_error — результат неизвестен, в том числе если ЮKassa не смогла дать точный ответ за 30 секунд. Повтори запрос с тем же ключом идемпотентности или запроси объект через GET. Если ошибка держится больше получаса — в поддержку.

Ограничения

Идемпотентность действует 24 часа после первого запроса, затем повтор обрабатывается как новый запрос. Idempotence-Key — не длиннее 64 символов.

Если за короткое время запросов слишком много, API возвращает HTTP 429. При статусе pending и ошибках 500 или 429 повторяй запрос с возрастающим интервалом.

Списки отдают не больше 100 объектов за запрос (limit), дальше — по cursor. Платежи и возвраты доступны за последние 3 года.

Источники

• Справочник API ЮKassa
• Спецификация OpenAPI
• Формат взаимодействия
• Коды ответов HTTP
• Входящие уведомления
• Платеж по сохраненному способу оплаты
• Значения параметров для Чеков от ЮKassa

---

Если этого недостаточно — официальная документация: https://yookassa.ru/developers/api JSON: https://mcp-everything.ru/api/integrations/yookassa. MCP: https://mcp-everything.ru/mcp