Уведомления — API ЮMoney для сбора денег

Уведомления

Самый простой способ получать информацию о переводах — подключить уведомления по электронной почте в настройках кошелька ЮMoney. Сообщения будут приходить на адрес, привязанный к кошельку.

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

HTTP-уведомления можно получать только на один адрес сервера. Если у вас несколько сайтов и разные формы, с помощью которых вы собираете переводы на один кошелек ЮMoney, на сервере нужно настроить разбор поля label. Например: label=XXyyyyyy, где ХХ — ID магазина, а уууууу — номер транзакции.

HTTP-уведомления

Уведомление отправляется при получении перевода из кошелька или с банковской карты.

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

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

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

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

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

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

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

Параметр	Тип	Описание
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 параметров уведомления.
unaccepted	boolean	Перевод еще не зачислен. Получателю нужно освободить место в кошельке.

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

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

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

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

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

Всегда проверяйте значение параметра 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: 090a8e7ebb6982a7ad76f4c0f0fa5665d741aafa

Примеры уведомлений

Уведомление о переводе с карты

operation_id = 441361714955017004
notification_type = card-incoming
datetime = 2013-12-26T08:28:34Z
sha1_hash = ac13833bd6ba9eff1fa9e4bed76f3d6ebb57f6c0
sender =
codepro = false
currency = 643
amount = 98.00
withdraw_amount = 100.00
label = ML23045

Что почитать еще

Настройки HTTP-уведомлений Уведомление по электронной почте и смс