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 | |
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¤cy&datetime&sender&codepro¬ification_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