How to Accept Payments / Tools for Accepting Yandex.Money

Forms and buttons for accepting payments: extended features

Forms and buttons are for charity funds, crowdfunding organizations, and those who want to start raising Yandex.Money quickly—without integration and contract. Besides, these tools will do for developers of CMS modules.
If you need additional features or custom design, create your own form using these parameters.
 

Mandatory parameters

receiver—number of the Yandex.Money Wallet to which the senders' money is to be credited.
quickpay-form—determines transaction type. Possible values:
  • shop—for universal form
  • donate—for charity form
  • small—for a button.
  • targets (up to 150 characters)—payment destination.
    paymentType—payment method. Possible values:
  • PC—payment from a Yandex.Money Wallet
  • AC—from a bank card
  • MC—direct carrier billing.
  • sum—transfer amount.
    Parameters for calculating the commission
  • amount_due—amount to be received;
  • sum—amount to be debited
  • a—commission factor.
  • Commission depends on the payment method.
    Payment methodCommission index (a)ExpressionExample
    From a Wallet in Yandex.Money (PC)0.005 from the recipient,
    from the amount to be credited
    amount_due = sum − sum * (a / (1 + a) )The sender transfers 1,000 rubles from a Wallet; the recipient will get 995 rubles, 2 kopeks to the account.
    From a bank card (АС)0.02 from the recipient,
    from the amount to be debited
    amount_due = sum * (1 − a)The sender transfers 1,000 rubles from the card; the recipient will get 980 rubles to the account.
    Direct carrier billing (MC)Commission from the sender; depends on the operator
     

    Optional parameters

    formcomment (up to 50 characters)—transfer name in the sender's History.
    It is best to be created from the store and good's name. For instance, ‘My Store: white felt boots’.
    short-dest—transfer name on the confirmation page. We recommend assign it the same as formcomment.
    label (up to 64 characters)—a mark that a site or app assigns to a certain transfer. For instance, the order tag or identifier can be specified as a mark.
    comment (up to 200 characters)—a field for transmitting a commentary of the sender.
    successURL—URL address for redirecting to, when the transfer is performed.
    need-fio—request for the sender's full name.
    need-email—request for the sender's email address.
    need-phone—request for the sender's phone number.
    need-address—request for the sender's address.
    Please note:
  • we recommend requesting contact details only if they are truly required (so the sender won't need to fill in unnecessary fields);
  • if contacts only required for certain cases, you can change the parameter value (value="true"—request, value="false"—do not request).
  •  

    Receiving information about transfers: HTTP notifications

    The easiest way of getting information about transfers is to activate email notifications. We will send messages to your address linked with the Yandex.Money Wallet.
    If you want to know about an incoming transfer immediately and have each one of them identified, activate HTTP notifications. The service will transmit information about the amount, ‘label’ value, and contact details of the sender. (Sender's contact details are only transmitted via HTTPS.)
    Please note: You can receive HTTP notifications to only one server address. If you have several sites and different forms for accepting transfers to one Yandex.Money account, you can setup reviewing the field ‘label’. For instance: label=XXyyyyyy, where ХХ—store's ID and уууууу—transaction number.
     

    Format for HTTP notifications

    Notifications are sent in the following cases:
  • the user receives a transfer from another Yandex.Money user.
  • the user receives a deposit from a bank card via our universal form, form for charity organizations, or button.
  • The notificaiton is not sent if the user receives a deposit by a direct carrier billing.
     

    Request format

    The notification is made in the form of HTTP request sent to the address specified under the Wallet Settings as follows:
  • method—POST
  • each notification parameter is specified as key/value pair in the form of POST request parameter
  • MIME type—application/x-www-form-urlencoded
  • Character encoding—UTF-8.
  • Yandex.Money makes three attempts to delived the notification: immediately upon receiving the transfer, in ten minutes, and the last one in one hour.
    For accepting notifications, we recommend using HTTPS protocol (receiving sender's contact information is only possible via this protocol; HTTP does not transmit contacts). If you do not receive notifications, check your settings: whether your server address is correct, whether it is on at the moment (push ‘Test’ button). At that, an entry about an incoming transfer will be recorded to the Wallet History.
     

    Parameters for notifications

    HTTPSParameterTypeValue
    nonotification_typestringFor transfers from a Wallet—p2p-incoming. For transfers with a random card—card-incoming.
     operation_idstringOperation identifier in the History of the recipient's account.
     amountamountThe amount credited to the recipient's account.
     withdraw_amountamountThe amount debited from the sender's account.
     currencystringCurrency code—always 643 (Russian ruble according to ISO 4217).
     datetimedatetimeDate and time of transfer.
     senderstringFor transfers from a Wallet—the sender's account number.
    For transfers from a random card—the parameter includes empty string.
     codeprobooleanFor transfer form a Wallet—transfer is protected with a security code.
    For transfers with a random card—always ‘false’.
     labelstringMark of payment. If it is absent, the parameter includes an empty string.
     sha1_hashstringSHA-1 hash of the notification parameters.
     unacceptedbooleanThe transfer was not credited. The recipient needs to free up some space in her Wallet or enter a security code (if codepro=true) to collect the money.
    Yeslastname
    firstname
    fathersname
    string
    string
    string
    Full name of the sender. If you do not request it, the parameters include empty string.
     emailstringEmail address of the transfer sender. If email request is not complete, the parameter is an empty string.
     phonestringPhone number of the sender. If the phone was not requested, the parameter includes empty string.
     city
    street
    building
    suite
    flat
    zip
    string
    string
    string
    string
    string
    string
    Delivery address of the transfer sender. If address request is not complete, the parameter is an empty string.
     

    Response format

    The notification is considered accepted if the recipient returned the code HTTP 200 OK.
     

    Certification of authenticity and integrity of the notification

    One of the notification parameters, sha1_hash, includes the value of the hashing function SHA-1 resulted from reduction of notification parameters jointly with the secret word.
    Note. The secret word for checking the notifications is used as a secret shared between Yandex.Money and the app developer. This guarantees the notification cannot be forged. You can get the secret word under your account Settings.
    Always check sha1_hash value. You want it to make sure of the following:
  • integrity of the notification details
  • Yandex.Money is the sender.
  • To check the notification integrity and authenticity, calculate the hash according to the algorithm stated above. Compare the details you received with the value of sha1_hash in the notification.
    1. Create a string of notification parameters in UTF-8 encoding (where notification_secret is a secret word for verifying notificaitons).
    String format:
    notification_type&operation_id&amount&currency&datetime&sender&codepro&notification_secret&label
    Sample of 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
    2. Calculate SHA-1 hashing function value of the received string.
    3. Format the result to HEX-coded form.
    Sample of the calculated valued of the parameter sha1_hash:
    090a8e7ebb6982a7ad76f4c0f0fa5665d741aafa
     

    Parameter samples

    Notification about a transfer from a card performed with request of the sender's full name and address:
    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
    lastname = Johnson
    firstname = Adam
    fathersname = Bishop
    zip = 195123
    city = Saint Petersburg
    street = Paris Ave S
    building = 12
    suite = 12
    flat = 12
    phone =
    email =
    Sample of the same notification, but under the HTTP protocol:
    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
     

    General description of transfer processing

    1. The sender chooses how to transfer money: from an e-wallet or bank card.
    2. You break the transfer details down into parameters and transmit it using POST method at https://money.yandex.ru/quickpay/confirm.xml.
    3. If you request details from the sender, she proceeds to a special form to fill out; if you did not request details, the sender proceeds to the transfer confirmation page on our side.
    4. Money is debited from the sender's Wallet or card and credited to your account after deducting the commission.
    5. You get an HTTP notification or email message about the transfer.
    6. You analyze details of the incoming transfer (amount + label field value) and decide on further actions towards the sender.
     

    Code sample

    Crowdfunder Antony Stark raises money for his project through the form.
    Project name: Iron man
    Yandex.Money account number: 41001xxxxxxxxxxxx
    Purpose of transfer: for Arc Reactor
    Amount: 4,568.25 rub.
    Sender's commentary: I'd like it with a remote control.
    <form method="POST" action="https://money.yandex.ru/quickpay/confirm.xml">
        <input type="hidden" name="receiver" value="41001xxxxxxxxxxxx">
        <input type="hidden" name="formcomment" value="Project ‘Ironman’: Ark Reactor">
        <input type="hidden" name="short-dest" value="Project ‘Ironman’: Arc Reactor">
        <input type="hidden" name="label" value="$order_id">
        <input type="hidden" name="quickpay-form" value="donate">
        <input type="hidden" name="targets" value="transaction {order_id}">
        <input type="hidden" name="sum" value="4568.25" data-type="number">
        <input type="hidden" name="comment" value="I want it to have a remote control.">
        <input type="hidden" name="need-fio" value="true">
        <input type="hidden" name="need-email" value="true">
        <input type="hidden" name="need-phone" value="false">
        <input type="hidden" name="need-address" value="false">
        <label><input type="radio" name="paymentType" value="PC">Yandex.Money</label>
        <label><input type="radio" name="paymentType" value="AC">Bank card</label>
        <input type="submit" value="Перевести">
    </form>