Реестры успешных и возвращенных выплат
Протокол массовых выплат устарел. Если хотите делать выплаты по API, используйте API ЮKassa.
ЮKassa ежедневно формирует реестры успешных и возвращенных выплат. В реестрах — все операции за указанную дату (в период с 00:00:00 по 23:59:59 по московскому времени):
- в реестре успешных выплат — все зачисленные выплаты;
- в реестре возвращенных выплат — все возвращенные (полностью и частично) выплаты.
Реестры приходят на электронную почту, которую вы сообщили менеджеру при подключении. Реестры успешных и возвращенных выплат приходят разными письмами.
Если за указанную дату не было совершено никаких операций, придет пустой реестр.
Формат письма
Письма подписываются сертификатом ЮKassa (S/MIME подпись).
Тема электронного письма формируется по шаблону (нумерация сквозная):
РЕЕСТР ДЛЯ <Ваше название в ЮKassa> ЗА <дата выплат в формате ДД-ММ-ГГГГ>. №<номер>Во вложении к письму реестр в двух файлах:
- в формате CSV — для автоматической обработки;
- в формате XLS — для разбора вручную.
Формат имени файла реестра успешных выплат
settlement_file_<agentId><em><yyyy-mm-dd></em><номер>.csvsettlement_file_<agentId><em><yyyy-mm-dd></em><номер>.xlsФормат имени файла реестра возвращенных выплат
refund_<agentId><em><yyyy-mm-dd></em><номер>.csvrefund_<agentId><em><yyyy-mm-dd></em><номер>.xlsСтруктура реестра
Реестр содержит:
- заголовок с номером и датой реестра;
- перечень зачисленных или возвращенных выплат;
- сводную информацию по выплатам, включая баланс обеспечительного счета.
Реестр в формате CSV
Формат файла реестра соответствует рекомендации IETF RFC4180. Разделитель полей — точка с запятой «;». Кодировка символов — UTF‑8.
Текстовый формат CSV представляет собой набор строк, разделенных символом переноса строки (LF или CRLF). Каждая строка содержит поля, разделенные точкой с запятой «;». Если в значении параметра встречаются символы двойные кавычки «"», точки с запятой «;» или переносы строк, то такие параметры должны заключаться в кавычки «"».
Допустимо помещать в кавычки все поля, вне зависимости от присутствующего в них набора символов. Если поле не помещено в кавычки, то все «соседние» пробелы (до точек с запятой или до начала или конца строки) игнорируются.
Структура
Содержимое файла реестра состоит из следующих элементов:
- HD-строка — заголовок реестра;
- D-строки — информация о выплатах;
- TD-строка — контрольная строка, сумма всех выплат за указанный период;
Z-строка— маркер отсутствия выплат (присутствует, если за указанный период не было никаких операций).
Заголовок (HD-строка)
Заголовок реестра содержит идентификатор магазина в ЮKassa, номер реестра (идентификатор реестра) и отчетный период, за который сформирован реестр.
Формат заголовка реестра
HD;registerId;agentId;from;till
Параметры заголовка реестра
| Параметр | Тип | Описание |
|---|---|---|
| registerId | xs:long | Идентификатор сформированного реестра, уникальный на протяжении всей истории операций. |
| agentId | xs:long | Идентификатор вашего шлюза в ЮKassa. |
from | xs:dateTime | Начало отчетного периода, за который сформирован реестр, включительно («от» включая). Дата и время в формате ГГГГ-ММ-ДДТчч:мм:сс.ссс±чч:мм (ISO 8601). |
till | xs:dateTime | Конец отчетного периода, за который сформирован реестр, исключительно («до» не включая). Дата и время в формате ГГГГ-ММ-ДДТчч:мм:сс.ссс±чч:мм (ISO 8601). |
Пример заголовка реестра
HD;123456;2277;2015-07-01T00:00:00.000+03:00;2015-07-02T00:00:00.000+03:00
Информация о выплате (D-строка)
Для каждой операции, проведенной за отчетный период, формируется отдельная D-строка.
Формат строки с информацией о выплате
D;clientOrderId;amount;currency;dstAccount;processedDT;comission;comissionCurrencyCode;commissionVat;commissionVatCurrency
Параметры строки с информацией о выплате
| Параметр | Тип | Описание |
|---|---|---|
| dstAccount | YMAccount | Идентификатор получателя перевода, значение параметра dstAccount из запроса makeDeposition. |
| clientOrderId | ClientTransactionNumber | Уникальный номер транзакции в ЮKassa (string, до 32 символов). Значение параметра clientOrderId из запроса makeDeposition. |
processedDT | xs:dateTime | Время зачисления на счет получателя, приходит в ответе на makeDeposition. В случае возврата — время проведения операции возврата денег со счета получателя выплаты. Дата и время по часам ЮKassa в формате ГГГГ-ММ-ДДТчч:мм:сс.ссс±чч:мм (ISO 8601). |
| amount | CurrencyAmount | Сумма выплаты или возврата. Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Значение amount из запроса makeDeposition. |
| currency | CurrencyCode | Код валюты транзакции — целое беззнаковое число. Например: 643 — рубль РФ. |
comission | CurrencyAmount | Сумма комиссии, которую ЮKassa списала за проведение выплаты (без учета суммы НДС). Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Может отсутствовать, если вы подключились до августа 2019 г. Чтобы получать в реестрах информацию о комиссиях, напишите вашему менеджеру. |
| comissionCurrency | CurrencyCode | Код валюты комиссии — целое беззнаковое число. Например: 643 — рубль РФ. |
commissionVat | CurrencyAmount | Сумма НДС с комиссии ЮKassa. Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Если вы проводите выплаты с расчетного счета, НДС не списывается, поле будет пустым. Конкретные условия списания НДС прописаны в вашем договоре. |
| commissionVatCurrency | CurrencyCode | Код валюты суммы НДС — целое беззнаковое число. Например: 643 — рубль РФ. |
Пример строки
D;123;107.00;643;410010000400;2015-07-01T10:52:01.000+03:00;3.21;643;0.71;643
Контрольная строка (TD-строка)
Контрольная строка представляет собой сумму всех переводов по текущему реестру. Если переводов в указанный период не было, то реестр считается пустым и контрольная строка отсутствует.
Пустой реестр содержит только строку заголовка и нулевую строку (Z-строку).
Формат строки
TD;count;sum;currency;comissionSum;comissionCurrency;commissionVatSum;commissionVatSumCurrency
Параметры контрольной строки
| Параметр | Тип | Описание |
|---|---|---|
| count | xs:int | Количество выплат за указанный период. |
| sum | CurrencyAmount | Общая сумма выплат за указанный период. |
| currency | CurrencyCode | Код валюты общей суммы. |
| comissionSum | CurrencyAmount | Общая сумма комиссии за указанный период (без учета суммы НДС). |
| comissionCurrency | CurrencyCode | Код валюты общей суммы комиссии. |
| commissionVatSum | CurrencyAmount | Общая сумма НДС с комиссии ЮKassa за указанный период. |
| commissionVatSumCurrency | CurrencyCode | Код валюты общей суммы НДС. |
Пример строки
TD;86;88230.95;643;1163.25;643;255.80;643
Примеры реестров в формате CSV
Пример реестра
HD;123456;2277;2019-07-08T00:00:00.000+03:00;2019-07-09T00:00:00.000+03:00 D;123;107.00;643;41001000040;2019-07-08T08:49:48.648+03:00;3.21;643;0.71;643 D;124;200.00;643;41001000040;2019-07-08T10:37:39.974+03:00;6.00;643;1.32;643 TD;2;307.95;643;9.21;643;2.03;643
Пример пустого реестра
HD;123456;2277;2015-07-01T00:00:00.000+03:00;2015-07-02T00:00:00.000+03:00 Z
Примеры файлов
Пример реестра успешных выплат: settlement_file_123456_02.11.2026_31.csv
Пример реестра возвращенных выплат: refund_123456_02.11.2026_32.csv
Пример пустого реестра: settlement_file_123456_02.11.2026_34.csv
Реестр в формате XLS
Поля реестра
| Поле | Значение |
|---|---|
| Заголовок | |
| AGENT ID | Идентификатор вашего шлюза в ЮKassa. |
Дата | Дата в формате ДД.ММ.ГГГГВ реестр попадают выплаты, датированные этим числом. |
| № | Порядковый номер реестра. |
| Таблица | |
| Номер транзакции | Уникальный номер транзакции в ЮKassa (string, до 32 символов). Значение параметра clientOrderId из запроса makeDeposition. |
| Сумма | Сумма транзакции. Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Значение amount из запроса makeDeposition. |
| Валюта | Валюта транзакции. Трехбуквенный код, например: RUB — рубль РФ. |
| Идентификатор получателя | Идентификатор получателя перевода, значение параметра dstAccount из запроса makeDeposition. |
Дополнительные реквизиты | Одно из трех значений, зависит от назначения выплаты. На банковский счет: номер банковского счета получателя. На банковскую карту: синоним номера банковской карты. На баланс мобильного:
PROPERTY1 и PROPERTY передаются в склеенном виде. Присутствуют, если были переданы в запросе makeDeposition. |
ФИО получателя | Данные получателя перевода из запроса makeDeposition:
Передаются в склеенном виде, только для выплат на банковские карты или счет. Не передаются, если вы используете расчетный счет ЮBusiness (поле в реестре будет пустым). |
Время перевода | Время зачисления на счет получателя, приходит в ответе на makeDeposition. В случае возврата — время проведения операции возврата денег со счета получателя выплаты. Дата и время по часам ЮKassa в формате ГГГГ-ММ-ДДТчч:мм:сс.ссс±чч:мм (ISO 8601). |
Назначение | Счет, на который зачисляются деньги. Варианты:
|
Комиссия | Сумма комиссии, которую ЮKassa списала за проведение выплаты (без учета суммы НДС). Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Может отсутствовать, если вы подключились до августа 2019 г. Чтобы получать в реестрах информацию о комиссиях, напишите вашему менеджеру. |
| Валюта комиссии | Трехбуквенный код, например: RUB — рубль РФ. |
НДС с комиссии | Сумма НДС с комиссии ЮKassa. Разделитель дробной части — запятая, всегда ровно два знака после запятой, разделитель тысяч отсутствует. Если вы проводите выплаты с расчетного счета, НДС не списывается, поле будет пустым. Конкретные условия списания НДС прописаны в вашем договоре. |
| Валюта | Трехбуквенный код, например: RUB — рубль РФ. |
| Контрольная строка | |
| Баланс счета | Сумма обеспечения баланса выплат на момент формирования реестра. |
Пример файла
Пример реестра успешных выплат: settlement_file_123456_01.20.2026_33.csv
Что почитать еще