Notification of incoming transfer

In this section

Notification is sent if:

Attention! When receiving notifications, always check the status of the incoming transfer in the unaccepted and codepro fields.
  • If unaccepted=true, the transfer hasn't been credited to the user's account yet. In order to accept it, the user must complete additional steps. For example, to free up space on the account if the user's limit is reached. Or enter the secret code, if this is required for receiving the transfer.
  • If codepro=true, the transfer is protected by a secret code. To receive a transfer like this, the user must enter the secret code.

Request format

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

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

Yandex.Money makes three attempts to deliver the notification: immediately when the transfer is received, ten minutes later, and one hour later.

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). The record of the incoming transfer is saved in the wallet history.

Tip. 

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.

Table 1. Notification parameters

HTTPSParameterTypeDescription

no

notification_type string

For transfers from a wallet - p2p-incoming.

For transfers from another card - card-incoming.

operation_id stringOperation ID in the history of the account that is receiving the transfer.
amount amountOperation amount.
withdraw_amount amountThe amount of money withdrawn from the sender's account.
currency string

User's account currency code. Always 643 (ruble of the Russian Federation conforming to ISO 4217).

datetime datetimeTransfer timestamp (date and time).
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

For transfers from a wallet, the transfer has a protection code.

For transfers from any other card, it is always false.

label stringPayment label. If the payment does not have a label, the parameter contains an empty string.
sha1_hash stringSHA-1 hash of notification parameters.
test_notification booleanThis flag means this is a test notification. By default, omitted.
unaccepted booleanThis flag indicates that the user didn't receive the transfer. Possible reasons:
  • The payment was put on hold because the user's account reached the available remainder limit. It is displayed in the hold field in the response to the account-info method.
  • The transfer is protected by a secret code. In this case, codepro=true.

yes

lastname

firstname

fathersname

string

string

string

Full name of the transfer's sender. If this information was not requested, these parameters contain an empty string.
email stringEmail address of the transfer's sender. If the email address was not requested, this parameter contains an empty string.
phone stringPhone number of the transfer's sender. If the phone number was not requested, this parameter contains an empty string.

city

street

building

suite

flat

zip

string

string

string

string

string

string

The address specified by the sender for delivery. If the address was not requested, these parameters contain an empty string.

Response format

A notification is considered delivered if the recipient responded to the request with an HTTP 200 OK code.

Tip. 

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.

Verifying notification authenticity and integrity

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

Note. 

The secret word for verifying notification is like a secret shared between Yandex.Money and the application developer. This means that notifications can't be faked. You can get the secret word in the account settings.

Always check the value of the sha1hash parameter. This is necessary to:

  • Verify the integrity of the notification data.
  • Make sure that the notification was sent by Yandex.Money.

To check the integrity and authenticity of the notification, calculate the hash using the algorithm below. Compare the data obtained with the value of the sha1_hash parameter in the notification.

  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
    

    Example of a parameter string:

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

    Example of a parameter string with a payment label:

    p2p-incoming&1234567&300.00&643&2011-07-01T09:00:00.000+04:00&41001XXXXXXXX&false&01234567890ABCDEF01234567890&YM.label.12345
  2. Calculate the value of the SHA-1 hash function from the resulting string.
  3. Format the resulting value in HEX encoding.

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

    a2ee4a9195f4a90e893cff4f62eeba0b662321f9

Examples of parameters

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 = Иванов
firstname = Иван
fathersname = Иванович
zip = 125075
city = Москва
street = Тверская
building = 12
suite = 10
flat = 10
phone = +79253332211
email = adress@yandex.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