--- slug: "yookassa" name: "ЮKassa" vendor: "ЮMoney" industry: "finance" docsUrl: "https://yookassa.ru/developers/api" version: 1 updatedAt: "2026-10-11" --- # ЮKassa Отрасль: Платежи и финансы. Актуально на 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. Для повторной попытки создай новый платеж с новым ключом идемпотентности. ```bash 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, отменится сам, а деньги вернутся покупателю. ```bash 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. ```bash 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 платежа. ```bash 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. Подтверждение покупателя не требуется. ```bash 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 года. ```bash 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" } ``` Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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 | да | Идентификатор платежа. | Пример ответа: ```json { "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 } } ] } } ``` Пример ответа: ```json { "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 | Пример ответа: ```json { "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" } } ``` Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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 | да | Идентификатор возврата. | Пример ответа: ```json { "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 } ] } ``` Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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 | да | Идентификатор чека. | Пример ответа: ```json { "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 | нет | Только для тех, кто использует Сплитование платежей. Идентификатор магазина продавца, подключенного к вашей платформе, информацию о котором нужно получить. | Пример ответа: ```json { "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" } ``` Пример ответа: ```json { "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 Пример ответа: ```json { "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. | Пример ответа: ```json {} ``` ### 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" } ``` Пример ответа: ```json { "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 | да | Идентификатор сохраненного способа оплаты. | Пример ответа: ```json { "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" } ``` Пример ответа: ```json { "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. | Пример ответа: ```json { "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" } ``` Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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 | да | Идентификатор сделки. | Пример ответа: ```json { "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" } } ``` Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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) и конец выдачи не достигнут. | Пример ответа: ```json { "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 | да | Идентификатор выплаты. | Пример ответа: ```json { "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 Пример ответа: ```json { "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": "Иван" } ``` Пример ответа: ```json { "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. | Пример ответа: ```json { "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" } } ``` Пример ответа: ```json { "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. | Пример ответа: ```json { "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" } } ``` Пример ответа: ```json { "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. | Пример ответа: ```json { "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. | Пример ответа: ```json { "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-токена (партнерская программа) ```bash curl https://api.yookassa.ru/v3/payments/{payment_id} \ -H "Authorization: Bearer " ``` ### Ответ с ошибкой ```json { "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](https://yookassa.ru/developers/api) - [Спецификация OpenAPI](https://yookassa.ru/developers/using-api/openapi-specification) - [Формат взаимодействия](https://yookassa.ru/developers/using-api/interaction-format) - [Коды ответов HTTP](https://yookassa.ru/developers/using-api/response-handling/http-codes) - [Входящие уведомления](https://yookassa.ru/developers/using-api/webhooks) - [Платеж по сохраненному способу оплаты](https://yookassa.ru/developers/payment-acceptance/scenario-extensions/recurring-payments/pay-with-saved) - [Значения параметров для Чеков от ЮKassa](https://yookassa.ru/developers/payment-acceptance/receipts/54fz/yoomoney/parameters-values) --- Если этого недостаточно — официальная документация: https://yookassa.ru/developers/api JSON: https://mcp-everything.ru/api/integrations/yookassa. MCP: https://mcp-everything.ru/mcp