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 multipurpose form, 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
ParameterTypeDescription
notification_type
string
For transfers from a wallet — p2p-incoming
For transfers from another card — card-incoming.
operation_idstringOperation identifier in the buyer’s account history.
amountamountOperation amount.
withdraw_amountamountThe amount debited from the sender’s account.
currencystringUser’s account currency code. Always 643 (ruble of the Russian Federation conforming to ISO 4217).
datetimedatetimeDate 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.
codeprobooleanIndicates 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.
labelstringThe payment label. If the payment does not have a label, the parameter contains an empty string.
sha1_hashstringSHA-1 hash of notification parameters.
test_notificationbooleanThis flag means this is a test notification. By default, omitted.
unacceptedbooleanThis 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
lastnamestringFull name of the transfer’s sender. If this information was not requested, these parameters contain an empty string.
firstnamestring
fathersnamestring
emailstringEmail address of the transfer sender. If the email was not requested, the parameter contains an empty string.
phonestringPhone number of the transfer sender. If the phone number was not requested, the parameter contains an empty string.
citystringThe address specified by the sender for delivery. If the address was not requested, these parameters contain an empty string.
streetstring
buildingstring
suitestring
flatstring
zipstring
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