API ЮKassa
Помощь
Подключить ЮKassa
Расширенные реестры операций
С 1 февраля 2023 года мы запустили расширенный формат реестров.
Если вы самозанятый, используете Сплитование платежей, Безопасную сделку или подключили ЮKassa до 1 февраля 2023 года, у вас останутся стандартные реестры — смотрите инструкции для стандартных реестров
У всех остальных по умолчанию включены расширенные реестры.
Как получить реестр за период
В любой момент вы можете получить реестр за период (максимум — за три месяца).
  1. На странице Реестры операций нажмите кнопку Получить реестр.
    Файл реестра будет сформирован с теми настройками, которые вы видите на странице. Чтобы поменять их, нажмите Изменить настройки.
  2. Выберите нужный период, если нужно — укажите адрес для получения реестра (или несколько). Затем нажмите Отправить реестр — файл придёт на указанный адрес.
Как настроить получение реестров
ЮKassa отправляет реестры на адрес электронной почты, который указан на странице Реестры операций
Если в течение суток не было ни одного платежа или возврата, на почту придёт пустой реестр — в файле не будет ни одной операции. Если вы не хотите получать пустые реестры, отключите это в настройках: нажмите Изменить настройки, уберите галочку «Отправлять реестры, если не было операций», и нажмите Сохранить.
Куда отправлять реестры
На почту
Адрес почты для получения реестров можно в любой момент поменять в настройках на странице Реестры операций. Для этого нажмите Изменить настройки, укажите новый адрес электронной почты (или несколько адресов) и нажмите Сохранить.
На сервер
ЮKassa может отправлять реестры напрямую на ваш sftp-сервер. Если вам это нужно, напишите нам — на b2b_support@yoomoney.ru
Язык реестров
Можно получать реестры на русском или на английском языке. Чтобы изменить язык, на странице Реестры операций нажмите Изменить настройки, выберите нужный язык и нажмите Сохранить.
Формат файла
Реестр может быть в формате CSV или Excel.
Файл в формате CSV больше подходит для автоматизированной обработки реестров. В таком формате реестры приходят двумя отдельными письмами — одно с реестром платежей, другое с реестром возвратов.
Если вы разбираете реестры вручную, удобнее будут файлы Excel. В таком формате приходит одно письмо с Excel-файлом, в котором 2 вкладки — одна с платежами, другая с возвратами.
Чтобы изменить формат файла, на странице Реестры операций нажмите Изменить настройки, выберите нужный формат и нажмите Сохранить.
Дополнительные поля
В реестрах можно получать дополнительную информацию об операциях — для этого добавьте дополнительные поля в настройках.
На странице Реестры операций нажмите Изменить настройки, выберите нужные поля на вкладке Реестры платежей и Реестры возвратов и нажмите Сохранить.
После этого в файлы реестров будут добавлены новые столбцы (справа).
Важно При самостоятельной интеграции с ЮKassa по API в реестры можно добавить любые поля, которые вам нужны — не только те, которые есть в настройках. Это могут быть, например, поля с информацией из ваших внутренних систем (внутренний идентификатор заказа, идентификатор плательщика и так далее). Если вам это нужно, настройте передачу этих данных в параметрах metadata и напишите нам на b2b_support@yoomoney.ru, что хотите добавить данные из этих параметров в реестр.
Пример файла с реестром
Чтобы посмотреть, как выглядит готовый файл реестра с выбранными настройками, вы можете скачать пример.
Если вы скачиваете пример файла в формате CSV, то скачается только файл с реестром платежей.
Содержание реестров
Реестр платежей
В него попадают все успешные платежи (кроме платежей через СберБанк Бизнес Онлайн).
По умолчанию содержит поля:
Идентификатор платежаУникальный идентификатор платежа в ЮKassa (если у вас самостоятельная интеграция по API — приходит в ответе при создании платежа, в поле id).
Сумма платежаСумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
Валюта платежаТрехбуквенный код валюты (RUB — рубль РФ)
Сумма за вычетом комиссииСумма, которая зачисляется на ваш расчетный счет. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
Сумма комиссииСумма комиссии за проведение платежа.
Время платежа
Время подтверждения платежа в ЮKassa (в формате dd.MM.yyyy HH:mm:ss).
Пример: 18.06.2021 17:46:58
Идентификатор платежного средстваНомер кошелька ЮMoney, из которого произведена оплата. Для других способов оплаты — внутренний номер счета на стороне ЮKassa.
ОписаниеЗначение поля description (если у вас самостоятельная интеграции по API).
Тип платежа
Код способа оплаты
на стороне ЮKassa.
Имя плательщикаФамилия, имя и отчество владельца кошелька ЮMoney. Заполнено только при оплате из кошелька ЮMoney, если сумма платежа больше 15 000 рублей.
Адрес плательщикаАдрес владельца кошелька ЮMoney. Заполнено только при оплате из кошелька ЮMoney, если сумма платежа больше 15 000 рублей.
ИННИНН владельца кошелька ЮMoney. Заполнено только при оплате из кошелька ЮMoney, если сумма платежа больше 15 000 рублей.
Если нужно, в настройках реестров можно добавить следующие поля:
Поле в реестреОписание
Для выставленных счетов
Номер счётаНомер выставленного счёта
Куда отправлен счётПочта или номер телефона, на который отправлен счёт для оплаты.
ФИО плательщикаКак зовут получателя счёта.
Для платежей банковскими картами
Код авторизации платежаУникальный код операции, который присваивается банком.
RRN платежаИдентификатор банковской транзакции (Retrieval Reference Number) — номер, по которому можно найти информацию о платеже в банке плательщика.
Номер картыМаскированный номер карты, с которой совершён платёж.
Банк плательщикаНазвание банка, который выпустил карту плательщика.
Платежная система карты плательщикаВ какой платёжной системе работает карта (МИР, Visa, UnionPay или другой).
Пример реестра
РЕЕСТР ПЛАТЕЖЕЙ ПО ДОГОВОРУ НЭК.11322.23 (152368)
Дата платежей: 2022-12-15
Идентификатор платежа;Сумма платежа;Валюта платежа;Сумма за вычетом комиссии;Сумма комиссии;Время платежа;Идентификатор платежного средства;Описание;Тип платежа;Имя плательщика;Адрес плательщика;ИНН плательщика

276a9776-000f-5000-a000-179a4d5c6bad;2.00;RUB;1.93;0.07;15.12.2022 12:37:07;41001860899377;Заказ №72;AC;;;
21b212e1-0016-50fb-9000-07aebf184c41;8.00;RUB;7.72;0.28;15.12.2022 15:43:01;41001860899377;Заказ №73;PC;;;
21b212f1-000f-50fb-9000-0866ab629d70;4.00;RUB;3.86;0.14;15.12.2022 17:05:15;41001860899377;Заказ №74;AC;;;

Сумма принятых платежей типа AC: 6.00 RUB
Сумма принятых платежей за вычетом комиссии типа AC: 5.79 RUB
Сумма комиссии за принятые платежи типа AC: 0.21 RUB
Число платежей типа AC: 2

Сумма принятых платежей типа PC: 8.00 RUB
Сумма принятых платежей за вычетом комиссии типа PC: 7.72 RUB
Сумма комиссии за принятые платежи типа PC: 0.28 RUB
Число платежей типа PC: 1

Сумма принятых платежей: 14.00 RUB
Сумма принятых платежей за вычетом комиссии: 13.51 RUB
Сумма комиссии за принятые платежи: 0.49 RUB
Число платежей: 3

По договору НЭК.11322.23
Реестр возвратов
В этот реестр попадают все успешные возвраты платежей.
Содержит поля по умолчанию:
Поле в реестреОписание
Идентификатор возвратаУникальный идентификатор платежа в ЮKassa (если у вас самостоятельная интеграция по API — приходит в ответе при создании платежа, в поле id).
Идентификатор платежаУникальный идентификатор исходного платежа в ЮKassa.
Сумма возвратаСумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует.
Валюта возвратаТрехбуквенный код валюты (RUB — рубль РФ).
Время возврата
Время создания возврата в ЮKassa (в формате dd.MM.yyyy HH:mm:ss).
Пример: 18.06.2021 17:46:58
Идентификатор платежного средстваНомер кошелька ЮMoney, из которого произведена оплата. Для других способов оплаты — внутренний номер счета на стороне ЮKassa.
Сумма возврата в валюте товараСумма возврата в валюте товара, указанной в настройках магазина.
Валюта платежаТрехбуквенный код валюты (RUB — рубль РФ)
ОписаниеЗначение поля description
Тип платежа
Код способа оплаты
на стороне ЮKassa.
Если нужно, в настройках реестров можно добавить следующие поля:
Поле в реестреОписание
Для выставленных счетов
Номер счётаНомер выставленного счёта
Куда отправлен счётПочта или номер телефона, на который отправлен счёт для оплаты.
ФИО плательщикаКак зовут получателя счёта.
Для платежей банковскими картами
Код авторизации платежаУникальный код операции, который присваивается банком.
Номер картыМаскированный номер карты, с которой совершён платёж.
Банк плательщикаНазвание банка, который выпустил карту плательщика.
Платежная система карты плательщикаВ какой платёжной системе работает карта (МИР, Visa, UnionPay или другой).
Пример реестра
РЕЕСТР ВОЗВРАТОВ ПО ДОГОВОРУ НЭК.11322.23 (152368)
Дата возвратов: 2022-12-15

Идентификатор возврата; Идентификатор платежа; Сумма возврата; Валюта возврата; Время возврата; Идентификатор платежного средства; Сумма возврата в валюте товара; Валюта платежа;Описание; Тип платежа

21b212e1-0016-50fb-9000-07aebf184c41;21b212de-000f-50fb-9000-07958ca92b2a;12.29;RUB;15.12.2022 15:52:47;410031218790019;12.29;RUB;Комментарий к возврату;AC
21b212f4-0016-50fb-9000-0742ef0ad6bd;21b212f1-000f-50fb-9000-0866ab629d70;11.52;RUB;15.12.2022 15:53:07;410031218790019;11.52;RUB;Комментарий к возврату 2;AC


Сумма возвратов: 23.81 RUB
Число возвратов: 2

По договору НЭК.11322.23
Реестр B2B-Платежей
Поле в реестреОписание
Идентификатор платежаУникальный идентификатор платежа в ЮKassa (если у вас самостоятельная интеграция по API — приходит в ответе при создании платежа, в поле id).
Сумма платежаСумма транзакции. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует
Валюта платежаТрехбуквенный код валюты (RUB — рубль РФ)
Сумма комиссииСумма комиссии за проведение платежа. Разделитель дробной части — точка, всегда ровно два знака после точки, разделитель тысяч отсутствует
Время платежа
Время подтверждения платежа в ЮKassa (в формате dd.MM.yyyy HH:mm:ss).
Пример: 18.06.2021 17:46:58
Тип платежа
Код способа оплаты
на стороне ЮKassa.
Назначение платежаНазначение платежа, передается в СберБанк Бизнес Онлайн в момент создания черновика платежного поручения. Покупатель может изменить его при оплате через СберБанк Бизнес Онлайн.
Полное наименование организацииДанные юрлица, которое внесло платеж.
Сокращенное наименование организацииДанные юрлица, которое внесло платеж.
Адрес организацииДанные юрлица, которое внесло платеж.
ИНН организации-плательщикаДанные юрлица, которое внесло платеж.
КПП организации-плательщикаДанные юрлица, которое внесло платеж.
Наименование банка организацииДанные юрлица, которое внесло платеж.
Отделение банкаДанные юрлица, которое внесло платеж.
БИК банка-плательщикаДанные юрлица, которое внесло платеж.
Номер счета организацииДанные юрлица, которое внесло платеж.
Пример реестра
РЕЕСТР ПЛАТЕЖЕЙ ОТ ЮРИДИЧЕСКИХ ЛИЦ В ООО «Название магазина». № 3355
Дата платежей: 13.06.2018

Идентификатор платежа; Сумма платежа; Валюта платежа; Сумма комиссии; Время платежа; Тип платежа; Назначение платежа; Полное наименование организации; Сокращенное наименование организации; Адрес организации; ИНН организации; КПП организации; Наименование банка организации; Отделение банка организации; БИК банка организации; Номер счета организации; Идентификатор клиента

549755819524; 100500.00; RUB; 10500.00; 13.06.2018 17:46:58; 2S; Оплата по договору №123; Открытое акционерное общество «Название организации»; ОАО «Название организации»; проспект Мира, дом 1, Москва,123995, Россия; 0000000001; 000000001; ПАО «СБЕРБАНК России», Северо-Западный банк ПАО «СБЕРБАНК России»; 046015602; 123456789; 4999

Сумма принятых платежей типа 2S: 100500.00 RUB
Сумма комиссии принятых платежей типа 2S: 10500.00 RUB
Число платежей типа 2S: 1
Остаток обеспечения по b2b-платежам: 60000.00 RUB

Кому: ООО «Название магазина»
(По договору 111.1111.11)
Автоматизированная обработка реестров
Эта информация пригодится, если вы хотите настроить автоматизированную обработку реестров.
В формате CSV реестры с платежами и реестры с возвратами приходят в двух отдельных файлах, двумя письмами.
Пример названия для реестра платежей: yoomoney-payments-*shopId*-yyyy-MM-dd.csv
Пример темы письма с реестром платежей: РЕЕСТР ПЛАТЕЖЕЙ ЗА *дата* ДЛЯ *название магазина* (*shopId*)
Пример название для реестра возратов: yoomoney-refunds-*shopId*-yyyy-MM-dd.csv
Пример тема письма для реестра возвратов: РЕЕСТР ВОЗВРАТОВ ЗА *дата* ДЛЯ *название магазина* (*shopId*)
В формате Excel платежи и возвраты приходят в одном файле одним письмом.
Пример названия: yoomoney-operations-*shopId*-yyyy-MM-dd.xls
Пример темы письма: РЕЕСТР ПЛАТЕЖЕЙ И ВОЗВРАТОВ ЗА *дата* ДЛЯ *название магазина* (*shopId*)
Если реестр содержит больше 10 000 операций, то он придёт в нескольких файлах (по 10 000 операций в каждом и оставшиеся — в последнем). Тогда к названию файла добавляется номер части: «-part-1», «-part-2» и так далее, а к последней части — «-part-N-last.»
Пример: yoomoney-payments-*shopId*-yyyy-MM-dd-part-3-last.csv
Если вы получаете реестры на sftp-сервер, то при загрузке файла может возникнуть технические проблемы (например, временный сбой в работе интернета или сервера). В таком случае ЮKassa будет повторять попытки загрузить файл до тех пор, пока не получится. При каждой попытке к названию файла добавляется «attempt-N» (где N — номер попытки).
Пример: yoomoney-payments-*shopId*-yyyy-MM-dd-part-1-attempt-2.csv