Notifications about incoming transfers

Notification is sent if:

The user has a transfer from another YooMoney user;
The user has incoming funds from a bank card via the fundraising widget or button.

Request format

The notification is sent as an HTTP request to the address specified in the account settings, in the following format:

method—POST;
Key/value pairs for each notification parameter, packed as HTTP 1.1 POST request parameters;
MIME type—application/x-www-form-urlencoded;
character encoding—UTF‑8.

We make three attempts to deliver the notification: immediately after the transfer, in 10 minutes, and in an hour.

We recommend using the HTTPS protocol to get notifications. Note that you cannot get the sender’s contact information in notifications unless you are using this protocol. When using the HTTP protocol, contact data is not passed in notifications.

If the notifications do not arrive, check your settings: make sure the correct server address is indicated, and your server is currently available (you can use the Test button). In this case, the record of the incoming transfer is saved in the wallet history (when sending test notifications, the record in the history is not saved).

Notification parameters

Parameter	Type	Description
notification_type	string	For transfers from a wallet — `p2p-incoming` For transfers from another card — `card-incoming`.
operation_id	string	Operation identifier in the buyer’s account history.
amount	amount	Operation amount.
withdraw_amount	amount	The amount debited from the sender’s account.
currency	string	User’s account currency code. Always `643` (ruble of the Russian Federation conforming to ISO 4217).
datetime	datetime	Date and time of the transfer.
sender	string	For transfers from a wallet, this is the sender’s account number. For transfers from any other card, the parameter contains an empty string.
codepro	boolean	Indicates whether the transfer is protected with a security code. It’s no longer possible to make transfers with security codes via YooMoney, so the parameter always has the `false` value.
label	string	The payment label. If the payment does not have a label, the parameter contains an empty string.
sha1_hash	string	SHA-1 hash of notification parameters.
test_notification	boolean	This flag means this is a test notification. By default, omitted.
unaccepted	boolean	This flag indicates that the user didn’t receive the transfer. The transfer was put on hold because the user has reached the available remaining balance limit for their account. The amount put on hold is displayed in the `hold` field of the response to the account-info method.
HTTPS only
lastname	string	Full name of the transfer’s sender. If this information was not requested, these parameters contain an empty string.
firstname	string
fathersname	string
email	string	Email address of the transfer sender. If the email was not requested, the parameter contains an empty string.
phone	string	Phone number of the transfer sender. If the phone number was not requested, the parameter contains an empty string.
city	string	The address specified by the sender for delivery. If the address was not requested, these parameters contain an empty string.
street	string
building	string
suite	string
flat	string
zip	string

Notification of a transfer from a card requesting the sender’s full name, address, phone, email, and transmitting the hidden label field over the HTTPS protocol

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 = Ivanov
firstname = Ivan
fathersname = Ivanovich
zip = 125075
city = Moscow
street = Tverskaya
building = 12
suite = 10
flat = 10
phone = +79253332211
email = address@example.ru

Example of the same notification when the HTTP protocol is used

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

Response format

The notification is considered accepted if the recipient transmitted the HTTP 200 OK code in the response.

When receiving notifications, always check the status of the incoming transfer in the unaccepted field. If unaccepted=true, it means the transfer hasn’t been credited to user’s account yet because the available remaining balance limit was reached. In order to accept the transfer, the user has to free up space on their account.

To get the other payment parameters, including the “Payment comment”, call operation-details and specify the operation_id parameter that you received in the notification.

Certification of authenticity and integrity of the notification

One of the notification parameters, sha1_hash, contains the SHA-1 hash function value from packing notification parameters together with the secret word.

The secret word for checking the notifications is used as a secret shared between YooMoney and the app developer. This guarantees the notification cannot be forged. You can get the secret word in the account settings.

Always check the value of the sha1_hash parameter. You want it to make sure of the following:

integrity of the notification details;
YooMoney is the sender.

To check the notification integrity and authenticity, calculate the hash according to the algorithm stated above. Compare the data obtained with the value of the sha1_hash parameter in the notification.

Hash calculating

Step 1. Create a UTF‑8 string from the notification parameters (where notification_secret is the secret word for verifying notifications).

String format

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

Sample of the parameter string

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

Sample of the parameter string with the payment mark

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

Step 2. Calculate the value of the SHA-1 hash function from the resulting string.

Step 3. Format the resulting value in HEX encoding.

Example of the calculated value of the sha1_hash parameter for the last sample

a2ee4a9195f4a90e893cff4f62eeba0b662321f9