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

Если вы хотите мгновенно узнавать о поступлении денег и сразу идентифицировать каждый перевод, включите HTTP-уведомления.

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

пользователю пришел перевод от другого пользователя Ю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	Метка платежа. Если метки у платежа нет, параметр содержит пустую строку.
test_notification	boolean	Флаг означает, что уведомление тестовое. По умолчанию параметр отсутствует.
unaccepted	boolean	Признак того, что кошелек достиг лимита доступного остатка, и перевод захолдирован (заморожен) до тех пор, пока пользователь не освободит место в кошельке. В ЮMoney больше нельзя делать переводы с холдированием, поэтому параметр всегда имеет значение `false`.
sign	string	Подпись уведомления. Используется для проверки целостности и подлинности уведомлений. Подробнее о параметре sign и его использовании.
sha1_hash	string	Параметр устарел. Перестанет приходить в уведомлениях с 18 мая 2026 года. Для проверки подлинности и целостности уведомлений используйте параметр `sign`. SHA-1 hash параметров уведомления.
Только 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

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

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

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

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

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

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

После получения уведомления проверьте его подлинность и целостность с помощью подписи. Подробнее о подписи уведомления

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

Чтобы вы могли проверить подлинность и целостность полученного уведомления, в параметре sign возвращается подпись уведомления. Это HMAC-SHA256 в HEX-представлении, который рассчитывается от URL-кодированной строки всех параметров уведомления, кроме sign. Параметры в строке отсортированы по алфавиту.

Для вычисления подписи используется секретный ключ из ваших настроек HTTP-уведомлений. Он служит разделяемым секретом между ЮMoney и разработчиком приложения.

Храните секретный ключ в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).

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

Вычисление подписи уведомления

Шаг 1. Сформируйте строку для вычисления подписи:

Извлеките параметры уведомления.
Удалите параметр sign — он не участвует в формировании подписи.
Отсортируйте оставшиеся параметры по алфавиту (A-Z).
Примените URL-кодирование к значениям каждого параметра (в кодировке UTF-8, RFC 3986).
Объедините параметры в строку формата ключ=значение, разделяя их символом &. Пустые значения оставьте как key= (без пробелов).

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

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

Пример подготовленной строки для вычисления подписи

amount=0.99&building=12&city=%7B%25%20translate%20%25%7D%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0%7B%25%20%2Ftranslate%20%25%7D&codepro=false&currency=643&datetime=2014-04-28T16%3A31%3A28Z&email=address%40example.ru&fathersname=%7B%25%20translate%20%25%7D%D0%98%D0%B2%D0%B0%D0%BD%D0%BE%D0%B2%D0%B8%D1%87%7B%25%20%2Ftranslate%20%25%7D&firstname=%7B%25%20translate%20%25%7D%D0%98%D0%B2%D0%B0%D0%BD%7B%25%20%2Ftranslate%20%25%7D&flat=10&label=YM.label.12345&lastname=%7B%25%20translate%20%25%7D%D0%98%D0%B2%D0%B0%D0%BD%D0%BE%D0%B2%7B%25%20%2Ftranslate%20%25%7D&notification_type=p2p-incoming&operation_id=904035776918098009&phone=%2B79253332211&sender=41003188981230&sha1_hash=8693ddf402fe5dcc4c4744d466cabada2628148c&street=%7B%25%20translate%20%25%7D%D0%A2%D0%B2%D0%B5%D1%80%D1%81%D0%BA%D0%B0%D1%8F%7B%25%20%2Ftranslate%20%25%7D&suite=10&test_notification=false&unaccepted=false&withdraw_amount=1.00&zip=125075

Шаг 2. Вычислите HMAC-SHA256 от полученной строки, используя секретный ключ из настроек HTTP-уведомлений. Представьте результат в HEX (нижний регистр).

Пример подписи для ключа secret123

092318d12a1249b8ff5cb7b93e1b409a35bfe01eadee9525a147dc977b4eb056

Шаг 3. Сравните результат со значением параметра sign:

Если подписи совпадают — уведомление подлинное и не изменялось.
Если подписи не совпадают — уведомление было изменено или отправлено с неверным секретом.

Готово!