Уведомление о входящем переводе

Уведомление отправляется, если:

пользователю пришел перевод от другого пользователя ЮMoney;
пользователю пришло пополнение с банковской карты через виджет или кнопку для сбора денег.

Формат запроса

Уведомление отправляется как HTTP-запрос на адрес, указанный в настройках счета, в следующем формате:

метод — POST;
каждый параметр уведомления указывается парой ключ/значение в виде параметра POST-запроса;
MIME-тип — application/x-www-form-urlencoded;
кодировка символов — UTF‑8.

ЮMoney делают три попытки доставить уведомление: сразу при получении перевода, затем — через 10 минут, последняя — через час.

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

Если уведомления не приходят, проверьте настройки: правильно ли указан адрес вашего сервера и доступен ли сервер сейчас (используйте кнопку Протестировать). При этом запись о входящем переводе сохранится в истории кошелька (при отправке тестовых уведомлений запись в истории не сохраняется).

Параметры уведомления

Параметр	Тип	Описание
notification_type	string	Для переводов из кошелька — `p2p-incoming` Для переводов с произвольной карты — `card-incoming`.
operation_id	string	Идентификатор операции в истории счета получателя.
amount	amount	Сумма операции.
withdraw_amount	amount	Сумма, которая списана со счета отправителя.
currency	string	Код валюты счета пользователя. Всегда `643` (рубль РФ согласно ISO 4217).
datetime	datetime	Дата и время совершения перевода.
sender	string	Для переводов из кошелька — номер счета отправителя. Для переводов с произвольной карты — параметр содержит пустую строку.
codepro	boolean	Признак того, что перевод защищен кодом протекции. В ЮMoney больше нельзя делать переводы с кодом протекции, поэтому параметр всегда имеет значение `false`.
label	string	Метка платежа. Если метки у платежа нет, параметр содержит пустую строку.
sha1_hash	string	SHA-1 hash параметров уведомления.
test_notification	boolean	Флаг означает, что уведомление тестовое. По умолчанию параметр отсутствует.
unaccepted	boolean	Флаг означает, что пользователь не получил перевод. На счете получателя достигнут лимит доступного остатка, поэтому перевод заморожен. Сумма замороженных средств отображается в поле `hold` ответа метода account-info.
Только HTTPS
lastname	string	ФИО отправителя перевода. Если не запрашивались, параметры содержат пустую строку.
firstname	string
fathersname	string
email	string	Адрес электронной почты отправителя перевода. Если email не запрашивался, параметр содержит пустую строку.
phone	string	Телефон отправителя перевода. Если телефон не запрашивался, параметр содержит пустую строку.
city	string	Адрес, указанный отправителем перевода для доставки. Если адрес не запрашивался, параметры содержат пустую строку.
street	string
building	string
suite	string
flat	string
zip	string

Пример уведомления о переводе с карты с запросом ФИО, адреса отправителя, телефона, электронного адреса и передачей скрытого поля label по протоколу HTTPS

operation_id = 904035776918098009
notification_type = p2p-incoming
datetime = 2014-04-28T16:31:28Z
sha1_hash = 8693ddf402fe5dcc4c4744d466cabada2628148c
sender = 41003188981230
codepro = false
currency = 643
amount = 0.99
withdraw_amount = 1.00
label = YM.label.12345
lastname = Иванов
firstname = Иван
fathersname = Иванович
zip = 125075
city = Москва
street = Тверская
building = 12
suite = 10
flat = 10
phone = +79253332211
email = address@example.ru

Пример того же уведомления при использовании протокола HTTP

operation_id = 904035776918098009
notification_type = p2p-incoming
datetime = 2014-04-28T16:31:28Z
sha1_hash = 8693ddf402fe5dcc4c4744d466cabada2628148c
sender = 41003188981230
codepro = false
currency = 643
amount = 0.99
withdraw_amount = 1.00
label = YM.label.12345

Формат ответа

Уведомление считается принятым, если получатель ответил на запрос кодом HTTP 200 OK.

При получении уведомления всегда проверяйте статус входящего перевода по значению поля unaccepted. Если unaccepted=true, то перевод еще не зачислен на счет получателя, так как превышен лимит на доступный остаток. Чтобы принять перевод, получателю нужно освободить место на счете.

Чтобы получить остальные параметры платежа, включая «Комментарий к платежу», сделайте вызов operation-details и укажите параметр operation_id, который вы получили в уведомлении.

Удостоверение подлинности и целостности уведомления

Один из параметров уведомления, sha1_hash, содержит значение хэш-функции SHA-1 от свертки параметров уведомления совместно с секретным словом.

Секретное слово для проверки уведомлений используется как разделяемый секрет между ЮMoney и разработчиком приложения. Благодаря этому подделать уведомление невозможно. Секретное слово можно получить в настройках счета.

Всегда проверяйте значение параметра sha1_hash. Это нужно, чтобы удостовериться:

в целостности данных уведомления;
в том, что уведомление отправлено ЮMoney.

Чтобы проверить целостность и подлинность уведомления, рассчитайте хэш по алгоритму, приведенному ниже. Сравните полученные данные со значением параметра sha1_hash в уведомлении.

Расчет хэша

Шаг 1. Сформировать строку из параметров уведомления в кодировке UTF‑8 (где notification_secret — это секретное слово для проверки уведомлений).

Формат строки

notification_type&operation_id&amount&currency&datetime&sender&codepro&notification_secret&label

Пример строки параметров

p2p-incoming&1234567&300.00&643&2011-07-01T09:00:00.000+04:00&41001XXXXXXXX&false&01234567890ABCDEF01234567890&

Пример строки параметров с меткой платежа

p2p-incoming&1234567&300.00&643&2011-07-01T09:00:00.000+04:00&41001XXXXXXXX&false&01234567890ABCDEF01234567890&YM.label.12345

Шаг 2. Вычислить значение хэш-функции SHA-1 от полученной строки.

Шаг 3. Отформатировать полученный результат в HEX-кодированном виде.

Пример рассчитанного значения параметра sha1_hash для последнего примера

a2ee4a9195f4a90e893cff4f62eeba0b662321f9