ROBOKASSA. User manual

General

ROBOKASSA — is a service which helps Clients (Merchants/online stores, service providers) receive payments from Users (buyers) made through:

Registration and activation

If you decided to connect to ROBOKASSA, then you should start with Registration. You can choose to cooperate with ROBOKASSA either as:

  1. a Legal Entity. OOO, ZAO, OAO, Self-employed person, or NKO, BANK, FGUP, RNKO and etc (or any other form of incorporation);
  2. an Individual with payments being received;
  3.  an Individual with the ability to receive payments to QIWI Wallet.

Registration of new client

You can create an account in the system by clicking the following link to our website homepage: «Register now». After clicking it, the following page will pop up:

How to complete the fields? Please specify: Company Name

Company Name (full official name of the company or the shop).

Form of cooperation

Please specifyLegal Entity; Individual; Legal Entity (Nonresident).

Client Identifier

Client Identifier is a general identifier for all company’s employees. This is a Latin name of the store or the company which operates a number of stores.

Administrator Login

Login is a personal identifier of a particular employee who has access to your ROBOKASSA Client Account. The system uses the Login to identify the role of this employee in the company and grants access to some or other information. You can log in the system only if you type in your Login together with correct Client Identifier. Roles and access rights are distributed by the employee who plays the role of "Administrator". When the Client Account is created, the system creates an employee with the role of “Administrator” and respective rights by default. By default, he is offered login “admin”, which you can change immediately.

Administrator E-Mail

Information will be sent to this E-Mail box to enable you to log in the Client Account. This E-Mail will also be used to restore access to the employee account.

The password will be generated automatically and sent to the Administrator’s E-Mail together with other registration details.

Signing in and completing key registration details

Using the Client Identifier and Login that you specified upon registration and the password, which was sent to your E-Mail, please sign in your Client Account.

 After you sign in, you can set your own password for access to your Client Account (change the automatically generated password), if you wish to do so. This is done at Settings – My Access – Preferences.

 

Other registration details

You can skip the following steps and go further.

Settings

We also advise you to complete the following fields in section Settings: My Access - Contact Info specifying your identification details and contact information.

 

Mandatory fields

The following fields are mandatory:

Full name

The first name, any middle names, and surname of a person.

Full name (in genitive)

Please specify the full name (the first name, any middle names, and surname of a person) of the employee who will act as the Signatory.

Position

 Official position of the person specified in the document certifying the right of signature.

Document certifying the right of signature

Document certifying the right of signature – E.g.: Articles of Association, Power of Attorney, Deed of Delegation. This field is required to be completed if this employee will sign official documents and be specified as signatory in the identification details of your legal entity.

Main E-Mail

Key contact person E-Mail.

Phone

Key contact person Phone.

Non mandatory fields Phone / Fax

Fax number or additional phone number.

Skype

Skype account.

Address

Employee address, for example, home address.

Comment

Additional information about the employee, which you want to save.

For a Legal Entity

Please complete the following information about your company in section “Settings” – “Legal data”.

 

Company data Property type

Please, select the desired property from the list.

TIN

Please type in your Tax ID (Tax Identification Number). 10 digits for companies (OOO, OAO, ZAO) and 12 digits for Sole Proprietors.

KPP

Please type in your Code of Reason for Registration, 9 digits.

OGRN/OGRNIP

Please type in your Principal State Registration Number. 12 digits for companies  (OOO, OAO, ZAO) and 15 digits for Self-employed person.

Company Contact Details

General contact details (phone and fax) of your company and Finance E-Mail for electronic document exchange.

 

Addresses

Please specify all addresses you may have. 

 If they are identical, please complete only one block and leave all others blank Fields “flat” or “office” are mandatory.

Legal address

The official address of registration, location address of the permanent executive authority of the legal entity.

De facto address

The actual address  the place where your company actually carries out professional activities.

Postal address

The address to which your company will receive correspondence.

Contacts Signatory Details

The executive body or an attorney of your company can act as the Signatory. All documents will be generated in his name. He is selected from the list or by clicking the button “Add”.

Only those employees are admitted to this list, for whom the following fields are completed: Full Name Position Document.
Contact Details

Please specify the employee of your company who will be the key contact person and whom we can contact for any inquiries that may arise during our cooperation. He is selected from the list or by clicking the button “Add”.

Only those employees are admitted to this list, for whom the following fields are completed: Full Name, Email 1, Telephone 1.
If you are a Self-employed person

If you are a Self-employed person, you will be required to specify additional information apart from that specified for the Legal Entity:

 

Mandatory fields Full name

The first name, any middle names, and surname of a person.

Date of birth

Date of birth. (DD/MM/YY).

Place of birth

Enter your place of birth (as in passport).

Passport

Please, enter the series and passport number, date of issue and the authority which issued the document.

Certificate of registration

Please, enter the serial number of the certificate of registration of a person as a self-employed person, and the date of registration.

If you are an Individual

In section “Settings” – " Withdrawal methods” you will have to either apply for ROBOKASSA Card. This is a card of international payment system MasterCard offering all its opportunities. In order for the card to be issued, you will be required to provide scans of the two inside spreads of your passport:

    inside spread with the holder’s photo;

    inside spread with the domicile registration stamp.

The total file size may not be more than 3.5 Mb. The following file formats are allowed: .jpg, .doc or .pdf. The scans should be in legible form and free of any stains, blurs or other foreign bodies.

Or specify the number of your Yandex.Money, QIWI or WebMoney Wallet.

Withdrawal methods

Please specify the details of your settlement account in section “Settings” – “Withdrawal methods”. This is done by clicking “Add withdrawal method”.

The following window will pop up:

 

Choose the account type

Select the type of account with which you are going to work: cashless bank account or an ROBOKASSA Card.

Name

Please specify any simple name of this account. It may have any name that is convenient to you, i.e. any name which may come to your mind.

BIC

Please specify the Bank Identification Code of the bank with which your settlement account is opened.

Correspondent account

Please specify the Correspondent Account of the bank with which your settlement account is opened.

Account

The settlement account shall consist of 20 digits and start with '30111', '30231', '40201', '40406', '40501', '40502', '40503', '40601', '40602', '40603', '40701', '40702', '40703', '40802'

Creation of Shop

You can create your shop either on the homepage of your Client Account or in section “My Shops” by clicking the button “Add New”. Please complete all fields as appropriate at this page.

 

Register as

When you register a new shop, you can choose from the following connection types:

  • Legal entity or Self-employed person and receiving money to your account;
  • As an individual, to receive payments via ROBOKASSA;
  • As an individual only for billing.
After activation, the store can not change its type.
Shop name

This name will be shown to the client upon making payment through our interface.  

May contain no more than 40 characters.
Shop ID

The Shop ID  a shop designation is used by interface only for payment initialization for understanding Robokassa in which shop payment will be carried out. Shop ID may contain Latin letters, digits and symbols: . - _

Please do not mix Shop ID up with the Client Identifier
Postal address (Legal Entities only)

This field needs to be completed if you haven’t previously completed section "Addresses".

Legal Entities only.
Your Homepage URL

In other words, this is the address of your website homepage. E.g. http://www.robokassa.ru/. This URL will be used in section Technical Settings which will become available after you create your shop. 

Attention! After you activate your Shop, you will not be able to change this URL!
Shop Settlement Account

To be selected from the list, unless it was designated previously. Or you can create it by clicking button “Add”.

Responsible Person

This is your employee who will be responsible for liaison with ROBOKASSA on general issues and whom we can contact at any time. 

Those employees are admitted to this list, for whom the following fields are completed: Full nameE-Mail1 and Telephone.
Support

This is your employee who will be responsible for liaison with the buyers on the issues relating to processing of payments and delivery of goods. 

Those employees are admitted to this list, for whom the following fields are completed: Full namePositionE-Mail1 and  Telephone.
Section of our e-Shop Catalog where your Shop can be found

Please specify the section where your Shop will be placed. If you chose category “Other Goods” or a category which does not fully describe your operations, please provide more detailed information. E.g. select Section “Other Goods” and specify “discount coupons” as additional description. Please note that after you activate your Shop, you will have to generate a separate data change request in order to change the catalog sections that you associated with your Shop. Your request will be processed by our specialists.

Additional description of goods (services etc.)

If you choose "Other products" or a category that does not fully disclose your activity, please specify the information in more detail. For example: The "Other products" category and describe further  "discount coupons".

After completing all details, please remember to click green button “Create”. Otherwise, the Shop will not be saved in your Client Account.

Technical Settings

You can quickly switch to the settings of a particular store from the general list, which is visible on the front page and in the "My Shops", by pressing the "Shop settings" represented as an icon (see Picture).

Now you need to proceed to set up of the Technical Cooperation or delegate this task to the technical specialist responsible for your website operation. You should complete section “Technical Settings” of your Shop in accordance with our Technical Documentation or applicable CMS requirements. In this section, you need to specify the key parameters of cooperation between our system and your website. Menu

 

You can make changes to this section at any convenient time during or after Shop Activation.

Technical preferences The Shop Identifier

The Shop Identifier which you specified when creating the Shop is indicated in the first line.

The algorithm for calculating the hash sum or checksum

It specifies the method by which the parameter SignatureValue value will be calculated. The following algorithms for calculating hash: MD5, RIPEMD160, SHA1, SHA256, SHA384, SHA512. For more information about hashing algorithms can be found here.

Password #1

This is for the payment initiation interface. It must by at least 8 characters long and contain at least one letter and one digit.

Password #2

This is for the payment notification interface and XML-interfaces. It must by at least 8 characters long and contain at least one letter and one digit. 

These passwords must be different and under NO circumstances they may be the same as the password for log in your Client Account. For security reasons, the passwords will not be shown on the screen. Please write down/save both passwords and keep them in a safe place. You will need them for further setup of the scripts.

Result URL

We will use this URL to automatically notify you of successful payments. 

Without this URL, we do NOT guarantee correct operation of our system.
ResultUrl. Method of Data Dispatch

Please specify the method you would like to choose to receive information from us through these URL. Your technical specialist should know the Method of Data Dispatch or it can be specified in the operation manual to ROBOKASSA module in CMS you operate.

If your website (shop) operates so that every transaction is processed manually and payments are tracked by your employee, you may set up automatic email notifications. To do so, you should select E-Mail as the Method of Data Dispatch in field ResultURL and type in your E-Mail box, where you wish to receive notifications.

Example:

SMS Notification

Optional.

Attention! This is a chargeable service.
Success URL

The buyer will be redirected to this URL after successful payment.

SuccessUrl. Method of Data Dispatch

Near this URL you can find setting  Method of Data Dispatch. Please specify the method you would like to choose to receive information from us through this URL. Your technical specialist should know the Method of Data Dispatch or it can be specified in the operation manual to ROBOKASSA module in CMS you operate.

Fail URL

The buyer will be redirected to this URL after unsuccessful payment or failure to pay.

FailUrl. Method of Data Dispatch

Near this URL you can find setting  Method of Data DispatchPlease specify the method you would like to choose to receive information from us through this URL. Your technical specialist should know the Method of Data Dispatch or it can be specified in the operation manual to ROBOKASSA module in CMS you operate.

Test payments parameters The algorithm for calculating or checksum

It specifies the method by which the parameter SignatureValue value will be calculated. The following algorithms for calculating hash: MD5, RIPEMD160, SHA1, SHA256, SHA384, SHA512. For more information about hashing algorithms can be found here.

Password#1

Used for testing the shop payment initiation interface. Length must be at least 8 characters, must contain at least one letter and at least one digit.

Password #2

Used for testing the shop payment notification interface, and XML-interfaces. Length must be at least 8 characters, must contain at least one letter and at least one digit.

Passwords for test payments must not coincide with the working password shop.

Please note that if section Technical Settings is not duly completed, your website (shop) will not work properly with ROBOKASSA and your request for Activation will be denied.

Change of technical settings after activation

Details in section Technical Settings can be changed and saved without additional confirmation before Activation of your shop. After Activation, in order for your changes to be saved, you will need to enter the Confirmation Code which will be sent to the E-Mail of the employee who made these changes.

The Code will be valid for 20 minutes. After this, all changes you've made will be reversed.

Activation

After you have taken all above steps and set up ROBOKASSA script on your website, you may send a request to us for Activation of the Shop to enable processing of payments. This request shall be sent from Settings of your Shop (My Shops – Shop which needs to be activated) by clicking the button “Request for Activation”:

However, if you did not complete any important fields, which need to be used in operations, respective information will appear in the store settings and the button “Request for Activation” will be inactive:

If this information appears, you should check whether you correctly completed details of the Legal Entity and section Technical Settings.

Installation and setup of ROBOKASSA script (module)

Finally, you registered your Store, and now you need to take an important step - to install ROBOKASSA script on your website and make all necessary settings.

By clicking the links below, you can download off-the-shelf scripts in the programming language of your interest:

Or you can have a look at the off-the-shelf modules and operation manuals for different CMSs placed on this page.

Description of variables, parameters and values

For a start, we will see what parameters and variables are used in the scripts and what values can be used for them. And also what exactly do we need from all of this and for what.

Mandatory Parameters

Nothing will work without them!

MerchantLogin

Means the Shop Identifier in ROBOKASSA you specified upon creation of the Shop.

OutSum

Means the amount payable (in other words, the price of the order placed by the client). The format of presentation – dot-delimited digits. For example 123.45.

The amount should be denominated in RUB.

However, if the prices are denominated (e.g.) in USD on your website when issuing the invoice you need to specify the amount converted from USD to RUB. 

(see Optional Parameters OutSumCurrency).

InvDesc

Means description of the purchase. Only English or Russian letters, digits and punctuation marks may be used. Maximum 100 characters. In other words, this is the name of the goods the client is purchasing. This information is not reflected in ROBOKASSA interface and the E-Receipt we issue to the client after completion of payment. It may be reflected correctly if the optional parameter Encoding is activated (see Optional Parameters).

SignatureValue

SignatureValue –  checksum or hash sum, a line of a 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F) calculated by the method specified in the Technical Settings of the shop. It is generated in the line containing the following parameters delimited by ‘:’ followed by Password#1 (you prescribed this password when completing section Technical Settings): MerchantLogin:OutSum:InvId:Password#1 — if the parameter InvId has been transmitted, and: MerchantLogin:OutSum::Password#1 if the parameter InvId has  not been transmitted.

This is a very important parameter which ensures the security of payment and integrity of data transmission. If it is correctly compiled, no intruder will be able to forge any data in the payment transaction.

Optional Parameters

You may skip this block, if you do not wish to make a complex script or payment page, and proceed to section Simplest shop without an option to generate unique invoice number.

IncCurrLabel

Means proposed currency of payment. This is the payment option you recommend to your buyers/users.If this parameter is specified, then the buyer during the transition to the site ROBOKASSA will get to the payment page to select a payment method.

The user may change it in the process of payment.

The values for IncCurrLabel, i.e. currency labels, are available in section XML interfaces. Get Currencies Interface

InvId

Means your invoice number. The optional parameter, but we strongly recommend using it.

It should be unique each time your client is redirected for payment to our system. It may vary from 1 to 2147483647 (2^31-1). If it contains an empty value, is not specified or equal to zero, then we will assign unique invoice number automatically when initiating the transaction.

It is advisable to use this option only in very simple stores, where no control is required or only one type of goods is offered.
If this parameter is passed, it should be included in the calculation of the checksum (SignatureValue).
Culture

Optional, means language the client will use to communicate with your website. It can have the following values: en, ru.

This is in accordance with ISO 3166-1. i.e. you initially choose the language of ROBOKASSA interface the client will see.

If no language is chosen (used), then the language will be as in the regional settings of the client’s browser. If the regional settings are other than Russian, then English will automatically switch on.

Encoding

Means encoding, in which cash-desk HTML code will return. By default: windows-1251. The same parameter ensures that purchase description (sInvDesc) is correctly displayed in ROBOKASSA interface and that Additional User Parameters are correctly translated if their values are in a language other than English.

Email

The buyer’s E-Mail is automatically inserted into ROBOKASSA payment form. The user may change it in the process of payment. It will be used if the user already specified his contact E-Mail on your website.

ExpirationDate

Invoice expiration date. This parameter is used to forbid the ability to pay for user later than the date of issuing an invoice by the store. It should be noted that, in some cases, if the payment is made offline, for example: using the terminal or service of mobile shops, payment will be able to effect later than the expiration date of invoice.

Date passed to the format recommended by the ISO 8601 (YYYY-MM-DDThh: mm: ss.fffffff;ZZZZZ), where:

• YYYY  year, 4 digits;

• MM  month, 2 digits;

• DD  day of the month, 2 digits (01 to 31);

• T  Latin character «T» in upper case;

• hh  hours, 2 digits (24-hour format, from 00 to 23);

• mm  minutes, 2 digits (00 to 59);

• ss  second 2 digits (00 to 59) (optional);

• fffffff  from 1 to 7 digits of the fractional part of seconds (optional);

• ZZZZZ  handle time zone (optional). If it is missing, it is implied Moscow time (UTC + 03). It may be:

o + hh:mm or - hh:mm – offset from the UTC (indicates that the local time, which is a given number of hours and minutes ahead or behind UTC);

o symbol «Z» (should be in uppercase) indicates that the point in time represented in zone UTC (equivalent to 00: 00 and -00: 00).

OutSumCurrency

OutSumCurrency is the way to specify currency, where the shop issues the order value. The shop uses this parameter to avoid manual conversion of exchange. OutSumCurrency is additional parameter to OutSum. If this parameter is used OutSum will show the entire order value in currency which is specified in the OutSumCurrency. In this instance, the entire sum will be re-counted according to exchange rate of the Central Bank of Russia Federation on the day of payment and will be paid to the shop. It can have the following values: USD, EUR and KZT.

If you pass a parameter OutSumCurrency, it must be included in the calculation of the checksum (SignatureValue). In this case, the basis for calculation will look like this: MerchantLogin:OutSum:InvId:OutSumCurrency:Password#1.

Additional User Parameters

The Additional User Parameters are also optional but are for completely different purpose. These are those parameters which ROBOKASSA never processes but always returns to the Store in response messages.

If:

  • You are opening a store, which will offer a wide range of goods, sections, and product types.
  • Your website will offer a variety of different services.
  • A number of resources base on the same website.
  • And most common, if you need to use additional identification information of your clients, e.g. need to know his ID or Login on your website.

Then when starting a payment transaction you can transmit all this information to us.

Upon completion of the payment transaction, we will return these additional parameters to you. They must be generated as follows:

Always start with: Shp_SHP_shp_ 
They may look like this: Shp_1=1Shp_1=2 and etc,  or Shp_oplata=1Shp_oplata=2 and etc, or Shp_login=Vasya; Shp_name=Вася

MerchantLogin:OutSum:InvId:Пароль#1:Shp_id=126:Shp_login=Vasya.

Upon receiving notification from the ROBOKASSA, you (your script) can use them at your discretion. As an example, you will decide where to redirect the buyer and what to show him and what steps to take in principle.

t is very important that all parameters are listed alphabetically, if you have more than one parameter.

Example:

Shp_login=Vasya:Shp_name=Вася:Shp_oplata=1 (L – N – O)

If any user parameter is in Cyrillic letters (Shp_name=Вася), ), then it must be URL-coded before using it to calculate SignatureValue and sending it in the form. If you make a GET request, this parameter must be URL-coded again immediately before generating the request for initiation of payment.

A line in the sum can contain up to 2048 characters.

Each of these parameters MUST be included in the calculation of the checksum (SignatureValue). As at the start of operation and at  its completion. All parameters must always be sorted in alphabetical order.

Recurrent Payments

Recurrent payments can be necessary for some shops, for example periodical, monthly subscriptions, etc. The special parameters are used to make such kinds of payments easier.

On the first stage, user effects a common payment but it is required to add the special parameter along with the others. This parameter shows that this payment will be recurrent. After successful payment of the invoice, using a bank card shop gets the ability to effect the payment recurrently without user involvement. To do so, the shop makes a request to the special URL (https://auth.robokassa.ru/Merchant/Recurring) transferring the common parameters and specifying the invoice number that was paid on the first stage.

Parameters

Recurring

This parameter shows that this payment will be recurrent. The parameter is set to true.

PreviousInvoiceID

The shop transfers this parameter in the call, which is directed to URL https://auth.robokassa.ru/Merchant/Recurring and specifies there the number of the first payment in the series of recurrent payments. In addition, this call is transferred mandatory and optional parameters, with the following exceptions:

  • Parameters InvoiceID, E-Mail, PreviousInvoiceID must be included;
  • Parameters IncCurrLabel, ExpirationDate, Recurring must not be included.

Payment interface

Code of single "Pay" button cash desk

This is ROBOKASSA interface which offers to proceed to payment by clicking one button. 
Before this, the store must save the transmitted information (invoice number, amount, date of issue and additional parameters, if used). Below is the link to send the request for payment: 

https://auth.robokassa.ru/Merchant/PaymentForm/FormMS.js 
As a result, the form illustrated below will pop up:

You can see other variations of buttons here.

Request parameters MerchantLogin

Means the Shop Identifier in ROBOKASSA you specified upon creation of the Shop.

OutSum

Means the amount payable (in other words, the price of the order placed by the client. See Optional Parameters OutSumCurrency).

InvId

Means your invoice number. The optional parameter, but we strongly recommend using it (see Optional Parameters).

InvDesc

Means description of the purchase. Only English or Russian letters, digits and punctuation marks may be used. Maximum 100 characters. In other words, this is the name of the goods the client is purchasing. This information is not reflected in ROBOKASSA interface and the E-Receipt we issue to the client after completion of payment. It may be reflected correctly if the optional parameter Encoding is activated (see Optional Parameters).

SignatureValue

MD5 SignatureValue –  checksum or hash sum, a line of a 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F). It is generated in the line containing the following parameters delimited by ‘:’ followed by Password#1 (you prescribed this password when completing section Technical Settings): MerchantLogin:OutSum:InvId:Password#1 — if the parameter InvId has been transmitted, and: MerchantLogin:OutSum::Password#1 if the parameter InvId has  not been transmitted.

<? $mrh_login = "demo"; $mrh_pass1 = "password_1"; $inv_id = 0; $inv_desc = "Техническая документация по ROBOKASSA"; $out_summ = "8.96"; $crc = md5("$mrh_login:$out_summ:$inv_id:$mrh_pass1"); print "<html><script language=JavaScript ". "src='https://auth.robokassa.ru/Merchant/PaymentForm/FormMS.js?". "MerchantLogin=$mrh_login&OutSum=$out_summ&InvoiceID=$inv_id". "&Description=$inv_desc&SignatureValue=$crc'></script></html>"; ?>

Detailed description of all used parameters and their values you can find here. Please, note that this example assumes that algorithm for calculating the hash MD5 was selected in the Technical settings of the shop. 

To pay buyer goes to payment interface ROBOKASSA, chooses a payment method and makes a payment. Then the funds are transferred to your balance in the system ROBOKASSA, and we will send payment notification to your ResultUrl which you have registered.

Payment of arbitrary amount

If it is necessary to enable the buyers to specify the amount of payment themselves (e.g. to top up their accounts or make donations), you can place a form with the amount input field on your website. You can also specify the amount which will be offered in this form by default.

The code generating a request to ROBOKASSAROBOKASSA will return HTML code of the form (see below) in response to the request.

Examples of the code for the website:

<? $mrh_login = "demo"; $mrh_pass1 = "password_1"; $inv_id = 0; $inv_desc = "Техническая документация по ROBOKASSA"; $out_summ = "8.96"; $crc = md5("$mrh_login:$out_summ:$inv_id:$mrh_pass1"); print "<html><script language=JavaScript ". "src='https://auth.robokassa.ru/Merchant/PaymentForm/FormFLS.js?". "MerchantLogin=$mrh_login&DefaultSum=$def_sum&InvoiceID=$inv_id". "&Description=$inv_desc&SignatureValue=$crc'></script></html>"; ?>

The above example assumes that in the Technical Settings of the shop selected algorithm MD5 for calculating a hash.

Parameter OutSum is omitted  in this script.

Instead DefaultSum  is used, an amount displayed (offered for payment) in the form by default. There is also empty space in the formula to calculate SignatureValue instead of the order price: "$mrh_login::$inv_id:$mrh_Password#1".

Please note! Parameter OutSum is not used at all in this script! 

Please see more detailed description of all parameters and their values here.

Example of code with all parameters

Example of the code (PHP) to be installed on the website.

<? // регистрационная информация (логин, пароль #1) // registration info (login, password #1) $mrh_login = "demo"; $mrh_pass1 = "password_1"; // номер заказа // number of order $inv_id = 0; // описание заказа // order description $inv_desc = "Техническая документация по ROBOKASSA"; // сумма заказа // sum of order $out_summ = "10.96"; // тип товара // code of goods $shp_item = "2"; // предлагаемая валюта платежа // default payment e-currency $in_curr = ""; // язык // language $culture = "ru"; // формирование подписи // generate signature $crc = md5("$mrh_login:$out_summ:$inv_id:$mrh_pass1:Shp_item=$shp_item"); // форма оплаты товара // payment form print "<html>". "<form action='https://auth.robokassa.ru/Merchant/Index.aspx' method=POST>". "<input type=hidden name=MrchLogin value=$mrh_login>". "<input type=hidden name=OutSum value=$out_summ>". "<input type=hidden name=InvId value=$inv_id>". "<input type=hidden name=Desc value='$inv_desc'>". "<input type=hidden name=SignatureValue value=$crc>". "<input type=hidden name=Shp_item value='$shp_item'>". "<input type=hidden name=IncCurrLabel value=$in_curr>". "<input type=hidden name=Culture value=$culture>". "<input type=submit value='Оплатить'>". "</form></html>"; ?>

Detailed description of all used parameters and their values you can find here. Please, note that this example assumes that algorithm for calculating hash MD5 was selected in the "Technical settings" of the shop. 

Variations of buttons and forms

You can choose the size and look of the pay button and amount input form. Below are possible variations of the buttons and forms, as well as URLs which need to be used to obtain respective button/form.

Pay buttons

 

Amount input forms

Notification of payment (ResultURL)

ResultURL  is intended to automatically notify your website of successful payment.

In the case of successful payment, ROBOKASSA makes a request to  ResultURL specifying the following parameters (using POST or GET method depending on which of them is selected in settings)  OutSum, InvId and SignatureValue.

The data is always transmitted in UTF-8.
Parameters description OutSum

Means the amount payable (in other words, the price of the order placed by the client).

InvId

Means your invoice number.

SignatureValue

SignatureValue –  checksum or hash sum, a line of a 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F) calculated by the method specified in the Technical Settings of the shop. 

If this is the case, SignatureValue will be calculated by the following formula: OutSum:InvId:Password#2  if you did not transfer User Parameters  and: OutSum:InvId:Password#2:[User Parameters] if you transmit User Parameters.

For example, if you gave us the User Parameters with these values here:

  • OutSum = 100.26
  • InvId = 450009
  • Shp_login = Vasya
  • Shp_oplata = 1

  then the signature will be generated from the line100.26:450009:Password#2:Shp_login=Vasya:Shp_oplata=1.

About Password#2 you can read in the Technical Settings.

The script of ResultURL must check that the resulting of checksum is correct and matches the SignatureValue you have calculated according to the parameters you receive from ROBOKASSA, but not according to the local data of the shop.

If the checksums are equal, then your script should respond ROBOKASSA, that we understand that your script is working correctly and repeated notifications from our side is not required. The result must contain text OK, and setting InvId. For example, the result must contain OK5 for invoice number 5. 

If the checksums are not equal, then the received message is incorrect, and the situation requires parsing by the shop.

If E-Mail was selected in settings as a method of data dispatch, then in a case of successful payment ROBOKASSA will send you email containing all above listed parameters to the mailbox specified in the field ResultURL.

Payment is received:

Price: OutSum
inv_id: InvId
PaymentMethod: PaymentMethod
[User Parameters]

Regards,
Project ROBOKASSA

 

Redirecting the user in case of successful payment (SuccessURL)

If the payment is successfully completed, the Buyer may follow a link you specified in the Technical settings using the method you selected (GET or POST).

 Once the user follows this link with correct parameters (SignatureValue is matched), this will mean that the payment is successfully made.

However, for the purposes of additional protection, it is advisable that the payment is verified by the script that will be exercisable upon redirection to ResultURL or by way of making a request to Operation State  XML Interface, and provided only that the invoice number InvId exists in the store database.

As a matter of fact, the redirection of the user to SuccessURL is a formality, which needs only to return the user to your website and provide information to him that he did everything right and his order is waiting for him at a certain place. And you are required to confirm payment in your database and take all other steps necessary to deliver the purchase upon receipt of a notice to ResultURL. Indeed, this is where we automatically transmit details in support of payment (i.e. in any case and without the need for any steps on the part of the user). 

Parameters description OutSum

Means the amount payable (in other words, the price of the order placed by the client).

InvId

Means your invoice number.

SignatureValue

SignatureValue –  checksum or hash sum, a line of a 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F) calculated by the method specified in the Technical Settings of the shop. 

If this is the case, SignatureValue will be calculated by the following formula: OutSum:InvId:Password#2  if you did not transfer User Parameters  and: OutSum:InvId:Password#2:[User Parameters] if you transmit User Parameters.

For example, if you gave us the User Parameters with these values here:

  • OutSum = 100.26
  • InvId = 450009
  • Shp_login = Vasya
  • Shp_oplata = 1

  then the signature will be generated from the line100.26:450009:Password#2:Shp_login=Vasya:Shp_oplata=1.

About Password#2 you can read in the Technical Settings.
Culture

Optional, means language the client will use to communicate with your website. It can have the following values: en, ru.

This is in accordance with ISO 3166-1. i.e. you initially choose the language of ROBOKASSA interface the client will see.

If no language is chosen (used), then the language will be as in the regional settings of the client’s browser. If the regional settings are other than Russian, then English will automatically switch on.

User Parameters

Redirecting the user in case of failure to pay (FailURL)

In the case of failure to make payment, the Buyer will be redirected to the following URL.

This is done in order to enable the Merchant, for example, to unblock the ordered goods in stock. In case of failure to pay, the following parameters will be transmitted to the shop’s FailURL by the method selected upon registration:

Parameters description OutSum

Means the amount payable (in other words, the price of the order placed by the client. See Optional Parameters OutSumCurrency).

InvId

Means your invoice number. The optional parameter, but we strongly recommend using it (see Optional Parameters).

Culture

Means language the client will use to communicate with your website. It can have the following values: en, ruThis is in accordance with ISO 3166-1. i.e. you initially choose the language of ROBOKASSA interface the client will see.

 

Generally speaking, the redirection of the user to this address does not necessarily mean that the Buyer finally refused from making payment, because he can return to ROBOKASSA page by clicking the button "Back" in his browser. Accordingly, if the goods in stock are blocked for this order, in order to unblock them, it is advisable to verify the fact of failure to pay by giving request to XML interface for the results of this transaction, specifying invoice number nInvId existing in the Merchant’s shop database.

XML interfaces

General Information

XML interfaces are intended to create full-fledged ROBOKASSA interface with various information blocks for the clients of your store/website and to ensure deeper cooperation between your store/website and ROBOKASSA.

Attention! Outdated XML interfaces are described here.

The requests to the interfaces can be given through HTTP GET or HTTP POST, or these can be used as methods of XML web-service:

The response to HTTP GET/POST request will return in a form of XML document. The document will have the following structure:

<?xml version="1.0" encoding="utf-8" ?> <...> <Result> <Code>integer</Code> <Description>string</Description> </Result> <...> Запрошенные данные (возвращаются только в случае успешного выполнения запроса) Required data </...> </...>

Result contains information on the result of the request:

Result contains information on the result of the request Code

Means the result of the request. If successful - 0, otherwise the error code is specified. If when processing a request, an error occurs, the response will not contain any additional elements with the requested data.

Description

Means text description of the result of the request.

General error codes

General error codes that may return with all requests:

  •  no shop with this MerchantLogin is found or the shop has not been activated;
  • 1000  internal error.

The interface of getting list of currency

Returns the list of currencies available to pay for the orders from a particular store/website.

It is used to specify the value of IncCurrLabel and to display the available payment options right on your website if you wish to give more information to your clients.

Method name

GetCurrencies

URL for HTTP GET/POST requests

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetCurrencies

Request parameters MerchantLogin

Means Store Identifier, line. Details can be found here.

Language

Means language for the localized values in the response (currencies, payment methods and etc.). 
Possible values: 

  • ru  Russian;
  • en – English.

Example of HTTP GET request

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetCurrencies?MerchantLogin=demo&Language=ru

Form of response to HTTP GET/POST requests

<?xml version="1.0" encoding="utf-8" ?> <CurrenciesList xmlns="http://auth.robokassa.ru/Merchant/WebService/"> <Result> <Code>integer</Code> <Description>string</Description> </Result> <Groups> <Group Code="string" Description="string"> <Items> <Currency Label="string" Name="string" /> ... </Items> </Group> ... </Groups> </CurrenciesList>

Description of returned data Groups

Means groups of currencies; can be used to display currencies in a more convenient way in the user interface.

Code

Means group code.

Description

Means text description of the group.

Items

Means currencies of the group.

Label

Means currency code.

Name

Means currency name.

Error codes specific for this interface

N/a.

The interface of getting list of available payment methods

Returns the list of payment methods available to pay for the orders from a particular shop/website. It is used to display the available payment methods right on your website if you wish to give more information to your clients. The key difference from the Get Currencies – is that no detailed information is shown here for all payment options, while only payment groups/methods are displayed.

Method name

GetPaymentMethods

URL for HTTP GET/POST requests

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetPaymentMethods

Request parameters MerchantLogin

Means Store Identifier, line. Details can be found here.

Language

Means language for the localized values in the response (currencies, payment methods and etc.). 
Possible values: 

  • ru  Russian;
  • en – English.

Example of HTTP GET request

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetPaymentMethods?MerchantLogin=demo&Language=ru

Form of response to HTTP GET/POST requests

<?xml version="1.0" encoding="utf-8" ?> <PaymentMethodsList xmlns="http://auth.robokassa.ru/Merchant/WebService/"> <Result> <Code>integer</Code> <Description>string</Description> </Result> <Methods> <Method Code="string" Description="string" /> <Method Code="string" Description="string" /> ... </Methods> </PaymentMethodsList>

Description of returned data Methods

Means available payment methods.

Code

Means code of the payment method.

Description

Means text description of the payment method.

Error codes specific for this interface

N/a

The interface for calculating the amount payable including ROBOKASSA’s charge

Helps calculate the amount payable by the buyer including ROBOKASSA’s charge (according to the service plan) and charges of other systems through which the buyer decided to pay for the order. It may be used both for your internal payments and to provide additional information to the clients on your website.

Method name

GetRates

URL for HTTP GET/POST requests

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetRates

Request parameters

MerchantLogin

Means Store Identifier, line. Details can be found here.

IncCurrLabel

Means code of the currency for which the amount payable needs to be calculated. If this parameter is left blank, the calculation will be made for all available currencies.

OutSum

Means the amount the store wishes to receive. On the basis of this amount and prevailing exchange rates for each currency/payment option in the list, the amount payable by the client will be calculated.

Language

Means language for the localized values in the response (currencies, payment methods and etc.). 
Possible values: 

  • ru  Russian;
  • en – English.

Example of HTTP GET request

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/GetRates?MerchantLogin=demo&IncCurrLabel=&OutSum=10.45&Language=ru

Form of response to HTTP GET/POST requests

<?xml version="1.0" encoding="utf-8" ?> <RatesList xmlns="http://auth.robokassa.ru/Merchant/WebService/"> <Result> <Code>integer</Code> <Description>string</Description> </Result> <Groups> <Group Code="string" Description="string"> <Items> <Currency Label="string" Name="string"> <Rate IncSum="decimal" /> </Currency> ... </Items> </Group> ... </Groups> </RatesList>

Description of returned data Groups

Means groups of currencies; can be used to display currencies in a more convenient way in the user interface.

Code

Means group code.

Description

Means text description of the group.

Items

Means currencies of the group.

Label

Means currency code.

Name

Means currency name.

Rate/IncSum

Means amount payable by the user including service charge.

Error codes specific for this interface

N/a

The interface for outgoing summ calculation

Helps calculate the amount receivable on the basis of ROBOKASSA prevailing exchange rates from the amount payable by the user.

Method name

CalcOutSumm

URL for HTTP GET/POST requests

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/CalcOutSumm

Request parameters

MerchantLogin

Means Store Identifier, line. Details can be found here.

IncCurrLabel

Means code of the currency for which the amount payable needs to be calculated. If this parameter is left blank, the calculation will be made for all available currencies.

IncSum

Means amount payable by the user.

Example of HTTP GET request

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/CalcOutSumm?MerchantLogin=demo&IncCurrLabel=YandexMerchantOceanR&IncSum=100

Form of response to HTTP GET/POST requests

<?xml version="1.0" encoding="UTF-8"?> <CalcSummsResponseData xmlns="http://auth.robokassa.ru/Merchant/WebService/"> <Result> <Code>integer</Code> </Result> <OutSum>string</OutSum> </CalcSummsResponseData>

Description of returned data OutSum

Means the amount the store wishes to receive.

Error codes specific for this interface

N/a

Operation State Interface

Returns detailed information on the current status and payment details.

Please bear in mind that the transaction is initiated not when the user is redirected to the payment page, but later – once his payment details are confirmed, i.e. you may well see no transaction, which you believe should have been started already.

Method name

OpState

URL for HTTP GET/POST requests

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/OpState

Request parameters

MerchantLogin

Means Store Identifier, line. Details can be found here.

InvoiceID

Means invoice number, integer.

Signature

SignatureValue –  checksum or hash sum, a line of 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F) calculated by the method specified in the Technical Settings of the shop. It is generated in the line containing the mandatory parameters delimited by ‘:’ followed by Password#2 (you prescribed this password when completing section Technical Settings): MerchantLogin:InvoiceID:Password#2.

 

Example of HTTP GET request

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/OpState?MerchantLogin=demo&InvoiceID=1932809606&Signature=9e2bf657364d25acf5905b4ac4f50e39

 

Form of response to HTTP GET/POST requests

<?xml version="1.0" encoding="utf-8" ?> <OperationStateResponse xmlns="http://auth.robokassa.ru/Merchant/WebService/"> <Result> <Code>integer</Code> <Description>string</Description> </Result> <State> <Code>integer</Code> <RequestDate>datetime</RequestDate> <StateDate>datetime</StateDate> </State> <Info> <IncCurrLabel>string</IncCurrLabel> <IncSum>decimal</IncSum> <IncAccount>string</IncAccount> <PaymentMethod> <Code>string</Code> <Description>string</Description> </PaymentMethod> <OutCurrLabel>string</OutCurrLabel> <OutSum>decimal</OutSum> </Info> </OperationStateResponse>

Description of returned data State

operation current state.

Code

Operation current state code. Possible values:

  • 5  initiated, payment is not received by the service.

    Input money state. This means that the user has not paid or payment system through which the user makes the payment  has not confirmed the payment yet.

  • 10  payment was not received, operation canceled.

    Payment has not been made. The buyer refused to pay or has not paid, and the operation is canceled due to timeout. Either the payment was made after the timeout. In the case of contentious issues at the request of the shop or buyer, the operation will be rechecked by customer support, and depending on the results can be transferred to another state.

  • 50  payment received, payment is transferred to the shop account.

    Money transfer state. This means that the money is credited to a shop account.  In this state, the payment may be delayed for a while. In case of failure to notify the store of money on admission ResultUrl (url unavailable or your script generates incorrect answer) will be a delay of about 5 minutes. If the payment is in this state for a long time (over 20 minutes), it means that there is a problem with transfer funds to the shop. 

  • 60  payment was returned to buyer after it was received.

    The payment returned to the buyer account (wallet) through which the buyer made the payment .

  • 80  operation execution is suspended.

     Halt. This means that there was an emergency situation in  the transaction (payment interfaces are not available in the payment system etc.) or the operation was suspended by security system. Operations that are in this state will manage by our customer support in the manual mode.

  • 100  operation completed successfully.

    Payment is carried out successfully, the money credited to the balance of the shop, notification of successful payment sent to the shop.

RequestDate

date/time of the request response.

StateDate

Date / time of last change of payment operation state.  

Info

information about the operation.

IncCurrLabel

Means code of the currency used by the client.

IncSum

The sum paid by the client, in units of currency IncCurrLabel.

IncAccount

Client account number (wallet, credit card number)  in the payment system, used for paying.

PaymentMethod

payment method selected by the client.

Payment Code

payment method code.

Description

text description.

OutCurrLabel

currency received by the shop.

OutSum

sum credited to the shop account in the OutCurrLabel currency units.

Date/time type data format

Date/time are transmitted in the ISO 8601 (YYYY-MM-DDThh:mm:ss.fffff;ZZZZZ) format recommended standard, where:

  • YYYY  year, 4 digits;
  • MM  – month, 2 digits;
  • DD  – day, 2 digits (from 01 to 31);
  • T  Latin symbol "T" in the uppercase;
  • hh  hours, 2 digits (24-hour format, from 00 to 23);
  • mm  minutes, 2 digits (from 00 to 59);
  • ss  seconds, 2 digits (from 00 to 59);
  • fffffff   from 1 to 7 digits fractional seconds part;
  • ZZZZZ  description of the time zone can be:
    • +hh:mm or -hh:mm  offset from UTC (indicates that the local time is specified. It is a given number of hours and minutes ahead or behind UTC);
    • "Z" symbol (must be in the uppercase), means that time is represented in the UTC zone (equivalent to +00:00 and -00:00).

Example: 2010-02-11T16:07:11.6973153+03:00

Error codes specific for this interface

  • 1  invalid digital signature request;
  • 3  information about the operation with with such InvoiceID is not found.
  • 4  Two operations with the same InvoiceID found.

How to pay a commission for the buyer

Using XML-interface  for calculating the amount payable, you can pay  ROBOKASSA commission for the buyer (only for Individuals). The invoicing in ROBOKASSA remains the same; the system will add a commission to the amount that you transmit to us for invoicing. The interface allows you to calculate the amount your shop will receive so that the buyer does not pay ROBOKASSA commission.

 For example:

Let us assume that a product or service on your site is worth 100 rubles. If you divert the buyer to the ROBOKASSA payment page with this sum, our system will add to the 100 rubles a commission for example  – 5%. As a result, the customer will be invoiced at 105 rubles. Now we use this XML interface and make sure that the buyer paid $ 100, not 105,  and your shop compensates ROBOKASSA 5% commission.

The calculation must be carried before forwarding a client.

If the product or service on your site is worth 100 rubles, you are using an XML interface, calculate the amount your shop will get, if the buyer pays exactly 100 rubles using the selected payment method.

Example of a request for the shop:

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/CalcOutSumm?MerchantLogin=$mrh_login&IncCurrLabel=$inccurrlabel&IncSum=100

ROBOKASSA returns you to the amount that was calculated let it be 95.24 rubles.

Please note that the calculation is correct only for the chosen method of payment!

Now you can make a request to initialize the payment and specify as a parameter value OutSum 95.24 and as IncCurrLabel – $ inccurrlabel.

Do not forget that in the request for the payment initialization you must specify the parameter IncCurrLabel with the same label of currency that you used when calculating the amount.

Shop structures

Simplest shop without option to generate unique invoice number

Such shop is unable to control the receipt of payments and you will likely have to assign payment statuses and dispatch goods to the buyers manually.

The key scheme of the shop operation is as follows:

  • the user, after he has chosen the payment method and clicked the "Pay", is redirected to ROBOKASSA, page, where he makes the payment (and the money in your currency are credited to the shop’s account).
  • upon completion of the process, notice of successful transaction is given to the E-mail of the shop operator.  

In the section Technical settings:

  • The algorithm for calculating the hash  MD5 (default).
  • Result URL – e-mail of the store operator; E-Mail is the method of data dispatch;
  • Success URL  URL to which the buyer will be redirected after making the payment, the method of data dispatch is of no importance (this may be the website homepage or the page saying to the client that his payment is successful);
  • Fail URL  URL to which the buyer will be redirected after unsuccessful payment, the method of data dispatch is of no importance (this may be the website homepage or the page saying to the client that his payment is unsuccessful).

The script for such a store must be the simplest. Actually, it is not even the script what is needed, but the link to proceed to the payment page.

It is recommended to use the simplest text editor – Notepad.

Now we will see how to create such a link step by step:

  1. We will take the following off-the-shelf request which will redirect us to the payment page: 

    https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=[value]&OutSum=[value]&Description=[value]&SignatureValue=[value]   

  2. Now we insert the details we already have as described in Mandatory ParametersThis is done by replacing the variables with the appropriate values.

    For example:

    • MerchantLogin = demo

    (Shop Identifier specified in section Technical settings);

    • OutSum = 11

    (Goods Price specified on your website, RUB);

    • Description = Purchase in demo store

    (Purchase Description).

     The following link will be generated: https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=demo&OutSum=11&Description=Purchase in demo store&SignatureValue=[value]. 

  3. The last parameter SignatureValue is missing in the resulting link. And we have to calculate it.

    We will calculate it from the following data line:

    MerchantLogin:OutSum::Password#1

    We insert appropriate values into it:

    demo:11::[password#1]

    [password#1] –  this is the password you specified when completing section Technical settings.

    Please note! Parameter InvId is used at in the counting SignatureValue with an void value. 
  4. In order to calculate MD5 SignatureValue, we can use one of the online calculators. For example, these ones: 
    http://sgeneri.ru/ 
    http://nekitbelov.wen.ru/online/md5.html
    http://md5info.ru/demo
  5. Now we will assemble the link to be placed on your website: 

    https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=demo&OutSum=11&InvoiceID=0&Description=Purchase in demo
    store&SignatureValue=56f978e24d1b51fa7b5ace90a4f4ba53 
    (You can use this link to make RUB 11 payment in our Demo Shop.)

     Following these steps, you will generate the link to be placed on your website without the need for any additional programming. And you can start accepting payments.

Shop with option to generate unique invoice number

The shop operation scheme is as follows:

  • the shop script generates the invoice unique number and signature and redirects the user to the payment page;
  •  after the payment is made ROBOKASSA notifies the shop of successful payment by sending a respective request to ResultURL. The script receives payment parameters signed by ROBOKASSA using Password#2. The script sets status "Paid" for this order in the shop database. If at the time of notice is given there is no communication link between ROBOKASSA and the shop, respective message is emailed to the administrator:

Payment is received:

Price: order price
inv_id: invoice number
PaymentMethod: PaymentMethod
shp_...

Regards,
Project ROBOKASSA

  • after the payment is made  the user is redirected to SuccessURL  ROBOKASSA transmits the same parameters as to ResultURL, but these ones are signed using Password#1

In the section Technical settings:

  • The algorithm for calculating the hash  MD5 (default).
  • Result URL – e-mail of the store operator; E-Mail is the method of data dispatch;
  • Success URL  URL to which the buyer will be redirected after making the payment, the method of data dispatch is of no importance (this may be the website homepage or the page saying to the client that his payment is successful);
  • Fail URL  URL to which the buyer will be redirected after unsuccessful payment, the method of data dispatch is of no importance (this may be the website homepage or the page saying to the client that his payment is unsuccessful).

The script for such a store must be the simplest. Actually, it is not even the script what is needed, but the link to proceed to the payment page.

It is recommended to use the simplest text editor – Notepad.

Now we will see how to create such a link step by step:

  1. We will take the following off-the-shelf request which will redirect us to the payment page: 

    https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=[value]&OutSum=[value]&Description=[value]&SignatureValue=[value]

  2. Now we insert the details we already have as described in Mandatory ParametersThis is done by replacing the variables with the appropriate values.

    For example:

    • MerchantLogin = demo

    (Shop Identifier specified in section Technical settings);

    • OutSum = 11

    (Goods Price specified on your website, RUB);

    • Description = Purchase in demo store

    (Purchase Description).

     The following link will be generated: https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=demo&OutSum=11&Description=Purchase in demo store&SignatureValue=[value].

  3. The last parameter SignatureValue is missing in the resulting link. And we have to calculate it.

    We will calculate it from the following data line:

    MerchantLogin:OutSum::Password#1

    We insert appropriate values into it:

    demo:11::[password#1]

    [password#1] –  this is the password you specified when completing section Technical settings.

    Please note! Parameter InvId is used at in the counting SignatureValue with an void value.
  4. In order to calculate MD5 SignatureValue, we can use one of the online calculators. For example, these ones: 
    http://sgeneri.ru/ 
    http://nekitbelov.wen.ru/online/md5.html
    http://md5info.ru/demo
  5. Now we will assemble the link to be placed on your website: 

    https://auth.robokassa.ru/Merchant/Index.aspx?MerchantLogin=demo&OutSum=11&InvoiceID=0&Description=Purchase in demo
    store&SignatureValue=56f978e24d1b51fa7b5ace90a4f4ba53 
    (You can use this link to make RUB 11 payment in our Demo Shop.)

     Following these steps, you will generate the link to be placed on your website without the need for any addition.

Full-fledged shop

The use of all ROBOKASSA options, such as Additional User Parameters and XML Interfaces, will enable you to integrate your shop into our system as deeply as possible. This will ensure higher flexibility in using ROBOKASSA which will help you provide services to your clients at a totally new level. 

XML Interfaces help in advance obtain exchange rates ROBOKASSA and the list of acceptable currencies, as well as calculate both the amount receivable by the shop and the amount payable by the buyer. This will significantly enhance your opportunities in building up a convenient user interface on your website.
Further, you can at any time check the payment status. This will provide higher stability and security to your operations. For example, your system will automatically check payment status directly with before delivery of the goods ROBOKASSA.

And if you prescribe Additional User Parameters, you will be able to tune up your website operation so that to offer the maximum comfort to your clients and employees. Specifically, this will enable you to distribute cash flows inside your resources from the services or goods that you offer. 
Alternatively, these parameters can be used to additionally identify your clients. This is often needed to ensure that the payment is credited correctly.

Manual processing of orders

If you wish the client to pay an invoice only after your manager checks the order and the client approve the supply package, or if you have no website and work, e.g. by phone, or you may find it difficult to understand all the technical aspects of connection to our system or have no money to engage a programmer, then it is advisable to use this mode of operation. In the Client Account, you may find section "Invoicing", which represents a user-friendly interface to create and email to the client the link to the payment page for a particular order which was checked by your manager and agreed with your client. 

In order to put in place this mode of operation with ROBOKASSA you need to take the following steps:

  1. Register at our website http://www.robokassa.ru/.
  2. Create your store in section Technical Settings and prescribe two passwords (this is mandatory)
  3. In fields ResultURL, choose E-Mail as a method of data dispatch and specify the mailbox where you want to receive notices of successful payments to be further processed by your manager.
  4. No other additional settings are needed, provided that you plan to work only manually.

Some specifics to be taken into account before redirecting the user to the payment page

If the goods on your website are offered on a one-of-a-kind basis or if the goods are reserved for a particular buyer for a certain period of time, then you should take into account the following aspects: 

  • The payment transaction starts only when the user clicks button "Pay"/"Checkout" in ROBOKASSA interface.  (it is at this moment that the time allocated for payment starts to run),
    i.e. even if the user moved to ROBOKASSA, the interface from your website, selected (or viewed) the payment option, but did not initiate the transaction by clicking the button "Pay"/"Checkout", no records will be kept in ROBOKASSA system.
  • Certain payment methods may provide for 1-2 hour timeout, while others may require from one day to a week. 

If you want to go into details:

  • Bank cards and electronic payment systems (e-money):WebMoney, Yandex.Money, WalletOne and etc. – the time allocated for payment is 45 minutes.
  • For terminals: QIWI, Elecsnet, and etc –  the time allocated for payment is two days (48 hours). Except for QIWI – one day (24 hours).
  • For online-banking systems: Alfa-Click, VTB24, QBank, Petrokommerz and etc. – the time allocated for payment is 1 day (24 hours).
  • For ATMs  the time allocated for payment is 1 day (24 hours).
  • For other payment methods: Mobile commerce (1 hour), Svyaznoy, Evroset (2 days)

There are some other aspects that you should also pay attention to  the user made payment, but the waiting period (usually if the payment is made by e-money) expires or the system through which the payment was made fails to send us confirmation of such payment and it was cancelled in our system, or the payment was made with an error and additional identification and corrections are required to be made manually. And after this, the client communicates that he made payment, but received nothing. So he then starts looking for his money and goods. This may happen on the same day, after several hours or months. 

If payment is actually confirmed, ROBOKASSA takes all necessary steps to complete the payment and send you a notification about this. Accordingly, this can happen after a long period of time. Normally, no more than a day, but sometimes it can be a long delay.

Operations with the Test Server. Debugging, check, setup

The test environment is an interface "payment page" ROBOKASSA, but without the ability to carry out the payment. It allows you to debug the process of payment and use test XML-interface obtaining the status of payment.

To work in test mode required parameter is IsTest.

Attention! To work in text mode use a special test set of passwords that do not match with the basic working password of your shop. They are written in a special unit in the Technical setttings of your shop. This is done to ensure the security of your online shop, so the attacker was not able to "cheat" your online shop.

Payment interface

Working in test environment requires an additional set of passwords that may not coincide with the Password#1 and  Password#2. They are found in a special section of Technical Settings. There is chosen for calculating the hash algorithm for test payments. Checksum algorithm for the test mode must be the same workers.

 

You can initialize a test payment via your ROBOKASSA Personal Account, through your shop using the modified script or manually assemble a link to the payment page ROBOKASSA.

In order to initiate test operation of payment through your shop, you must add the parameter IsTest with the value 1 to the  script.

If this parameter is absent, or as a parameter value IsTest was transferred to 0, or the value is empty, such a request is not considered as a test payment and initializes the normal payment operation.

Initialization of the test payment through the shop

Consider testing details of payment through your shop using the modified script:

  1. We use this script;
  2. Here have already been replaced [value] appropriate data (for more details you can read here), should be taken similar steps to test your shop:

    • MerchantLogin = Test1999

      (the Shop Identifier from Technical settings);

    • Pass1 = Password#1

      (Password#1 from Test payments parameters);

    • InvId = 678678

      (invoice number);

    • OutSum = 100

      (cost of goods, RU);

    • Description = Goods

      (description of the purchase);

    • IsTest = 1

      ( a marker to test payment);

  3. Set the notify of payment on ResultURL to work with the test interface. This will require a Password#2 from the test parameters into an accounting of SignatureValue.
  4. After saving these settings, you can initiate a test payment operation from your shop. 
  5. As a result, you find yourself here, and you can continue to test the payment process in your shop.

Initialization of the test payment through the ROBOKASSA Personal Account

Let us consider test details of payment via ROBOKASSA Personal Account.

Please note that the test through ROBOKASSA Personal Account not a substitute for a shop test via the shop's website.

 

Enter your invoice number, the sum of the order, and (optionally) add the desired parameters.After clicking on the button "Generate link"  parameters will be checked and SignatureValue will be counted. After pressing the button "Check" you will be directed to pay in ROBOKASSAIn the section "Selecting a method of payment" you will be asked to choose one or another method of payment of the test order.

The process of test payment

After you press "Pay" on the page of your ROBOKASSA Personal Account it will move you to the payment page of the test ROBOKASSA site.

After selecting a payment method, you can go to the payment.

Or go back and choose another payment method.

After you press the "Go to payment", you will be taken to a special page where you can pay the test to choose one of two possible endings: success or failure.

An example of successfully passing the test payment.

 

An example of a fail test payment.

Please note that the test payments do not appear in the search operations in the ROBOKASSA Personal Account.

PHP code with the parameter IsTest

<? $mrh_login = "demo"; $mrh_pass1 = "password_1"; $inv_id = 0; $inv_desc = "Техническая документация по ROBOKASSA"; $out_summ = "8.96"; $crc = md5("$mrh_login:$out_summ:$inv_id:$mrh_pass1"); print "<html>". "<form action='http://test.robokassa.ru/Index.aspx' method=POST>". "<input type=hidden name=MrchLogin value=$mrh_login>". "<input type=hidden name=OutSum value=$out_summ>". "<input type=hidden name=InvId value=$inv_id>". "<input type=hidden name=Desc value='$inv_desc'>". "<input type=hidden name=SignatureValue value=$crc>". "<input type=submit value='Оплатить'>". "</form></html>"; ?>

Operation State XML-Interface

This XML interface is needed to system debugging of an interaction of your shop/site with ROBOKASSA in the test mode.

This XML interface returns detailed information about the current status and details of the payment.

It should be remembered that the operation is not initiated at the time of user's transition to ROBOKASSA interface, it happens later  after the confirmation of his payment details, therefore you can not find an operation that, you think, has to begin. To test this XML interface, you should run a test operation of a payment

Method name

OpState

Request parameters MerchantLogin

Means Shop Identifier, line. Details can be found here.

InvoiceID

Means invoice number, integer.

IsTest

The parameter indicates that the request to the ROBOKASSA system will be test and payment won't be made.

Signature

SignatureValue –  checksum or hash sum, a line of a 32-bit 16-nary number in hex format and  any register (totally 32 characters 0-9, A-F) calculated by the method specified in the Technical Settings of the shop. It is generated in the line containing the mandatory parameters delimited by ‘:’ followed by Password#2 from Test payments parameters (you prescribed this password  in a special section of Technical Settings): MerchantLogin:InvoiceID:Password#2.

https://auth.robokassa.ru/Merchant/WebService/Service.asmx/OpState?MerchantLogin=Test1999&InvoiceID=100&IsTest=1&Signature=061d7da048c2edd112c7632399e727c0

Form of response to HTTP GET/POST requests

<operationstateresponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://merchant.roboxchange.com/WebService/"> <result> <code>0</code> </result> <state> <code>100</code> <requestdate>2015-12-01T19:05:38.4065961+03:00</requestdate> <statedate>2015-12-01T19:05:38.4065961+03:00</statedate> </state> <info> <inccurrlabel>YandexMerchantOceanR</inccurrlabel> <incsum>100.00</incsum> <incaccount>Тестовый аккаунт</incaccount> <paymentmethod> <code>EMoney</code> <description>Электронными деньгами</description> </paymentmethod> <outcurrlabel>BNR</outcurrlabel> <outsum>100.00</outsum> </info> </operationstateresponse>

Description of returned data State

operation current state

Code

Operation current state code.  In test mode, always:

  • 5  initiated, payment has not yet begun.
  • 10  operation canceled.
  • 100 – operation completed successfully.

    Payment is carried out successfully, notification of successful payment sent to the shop.

RequestDate

date/time of the request response.

StateDate

Date/time of the last operation state change.

Info

information about the operation.

IncCurrLabel

Means code of the currency used by the client.

IncSum

The sum paid by the client, in units of currency IncCurrLabel.

IncAccount

Client account number (wallet, credit card number)  in the payment system, used for paying.

PaymentMethod

payment method selected by the client.

Payment Code

payment method code.

Description

text description.

OutCurrLabel

currency received by the shop.

OutSum

the sum is credited to the shop account in the OutCurrLabel currency units.

Error codes specific for this interface
  • 1  invalid digital signature request;
  • 3  information about the operation with with such InvoiceID is not found.

Date/time type data format

Date/time are transmitted in the ISO 8601 (YYYY-MM-DDThh:mm:ss.fffff;ZZZZZ) format recommended standard, where:

  • YYYY  year, 4 digits;
  • MM  – month, 2 digits;
  • DD  – day, 2 digits (from 01 to 31);
  • T  Latin symbol "T" in the uppercase;
  • hh  hours, 2 digits (24-hour format, from 00 to 23);
  • mm  minutes, 2 digits (from 00 to 59);
  • ss  seconds, 2 digits (from 00 to 59);
  • fffffff   from 1 to 7 digits fractional seconds part;
  • ZZZZZ  description of the time zone can be:
    • +hh:mm or -hh:mm  offset from UTC (indicates that the local time is specified. It is a given number of hours and minutes ahead or behind UTC);
    • "Z" symbol (must be in the uppercase), means that time is represented in the UTC zone (equivalent to +00:00 and -00:00).

Example: 2010-02-11T16:07:11.6973153+03:00

Examples

The above example assumes that in the Technical Settings of the shop selected algorithm MD5 for calculating a hash.

PERL

URL for redirection of the customer to the service

# connect standard module for building MD5-signs use Digest::MD5 qw(md5_hex); # your registration data my $mrh_login = "test"; ### your login here my $mrh_pass1 = "securepass1"; ### merchant pass1 here # order properties my $inv_id = 5; ### shop's invoice number ### (unique for shop's lifetime) my $inv_desc = "desc"; ### invoice desc my $out_summ = "5.12"; ### invoice summ # build CRC value my $crc = md5_hex("$mrh_login:$out_summ:$inv_id:$mrh_pass1"); # build URL my $url = "https://auth.robokassa.ru/Merchant/Index.aspx?MrchLogin=$mrh_login&". "OutSum=$out_summ&InvId=$inv_id&Desc=$inv_desc&SignatureValue=$crc"; # print URL if you need print "Content-type: text/html\n\n"; print "<a href='/ru/$url'>Payment link</a>";

Verification of notification (ResultURL)

# as a part of ResultURL script # connect standard module for building MD5-signs use Digest::MD5 qw(md5_hex); # define function for retrieval http-paratemters sub http_Prm; # your registration data my $mrh_pass2 = "securepass2"; ### merchant pass2 here # load parameters my %q = http_Prm(); # loaded parameters: $q{OutSum}, $q{InvId}, $q{SignatureValue} $q{SignatureValue} =~ s/([a-z])/uc "$1"/eg; # force uppercase # build own CRC my $my_crc = md5_hex("$q{OutSum}:$q{InvId}:$mrh_pass2"); $my_crc =~ s/([a-z])/uc "$1"/eg; # force uppercase # define the correctness state my $is_correct = ($my_crc eq $q{SignatureValue} ? 1 : 0); if (!$is_correct) { print "Content-type: text/html\n\nbad sign\n"; die "incorrect sign passed"; } # OK state # print OK signature print "Content-type: text/html\n\nOK$q{InvId}\n"; # perform some action (change order state to paid) exit(); # just function to load http parameters, you can use own sub http_Prm { my %query; { # POST params my ($q_sz, $i, @q, @cmd); my $l = $ENV{'CONTENT_LENGTH'}; my $qtext = ""; while ($l>0) { $l-=sysread(STDIN, $qtext, $l, length($qtext)); } @q = split("&", $qtext); $q_sz = scalar(@q); for($i=0; $i<$q_sz; $i++) { @cmd = split("=", $q[$i]); $cmd[1] =~ s/\+/ /g; $cmd[1] =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $query{$cmd[0]} = $cmd[1]; } } { # GET params my ($q_sz, $i, $qtext, @q, @cmd); $qtext = $ENV{'QUERY_STRING'}; @q = split("&", $qtext); $q_sz = scalar(@q); for($i=0; $i<$q_sz; $i++) { @cmd = split("=", $q[$i]); $cmd[1] =~ s/\+/ /g; $cmd[1] =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $query{$cmd[0]} = $cmd[1]; } } return %query; }

Verification of operation parameters ("cashier check") in SuccessURL script

# as a part of SuccessURL script # connect standard module for building MD5-signs use Digest::MD5 qw(md5_hex); # define function for retrieval http-paratemters sub http_Prm; # your registration data my $mrh_pass1 = "securepass1"; ### merchant pass1 here # load parameters my %q = http_Prm(); # loaded parameters: $q{OutSum}, $q{InvId}, $q{SignatureValue} $q{SignatureValue} =~ s/([a-z])/uc "$1"/eg; # force uppercase # build own CRC my $my_crc = md5_hex("$q{OutSum}:$q{InvId}:$mrh_pass1"); $my_crc =~ s/([a-z])/uc "$1"/eg; # force uppercase # define the correctness state my $is_correct = ($my_crc eq $q{SignatureValue} ? 1 : 0); if (!$is_correct) { print "Content-type: text/html\n\nbad sign\n"; die "incorrect sign passed"; } # you can check here, that resultURL was called # (for better security) # OK, payment proceeds print "Content-type: text/html\n\n"; echo "Thank you for using our service\n"; exit(); # just function to load http parameters, you can use own sub http_Prm { my %query; { # POST params my ($q_sz, $i, @q, @cmd); my $l = $ENV{'CONTENT_LENGTH'}; my $qtext = ""; while ($l>0) { $l-=sysread(STDIN, $qtext, $l, length($qtext)); } @q = split("&", $qtext); $q_sz = scalar(@q); for($i=0; $i<$q_sz; $i++) { @cmd = split("=", $q[$i]); $cmd[1] =~ s/\+/ /g; $cmd[1] =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $query{$cmd[0]} = $cmd[1]; } } { # GET params my ($q_sz, $i, $qtext, @q, @cmd); $qtext = $ENV{'QUERY_STRING'}; @q = split("&", $qtext); $q_sz = scalar(@q); for($i=0; $i<$q_sz; $i++) { @cmd = split("=", $q[$i]); $cmd[1] =~ s/\+/ /g; $cmd[1] =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; $query{$cmd[0]} = $cmd[1]; } } return %query; }

PHP

URL for redirection of the customer to the service

// your registration data $mrh_login = "test"; // your login here $mrh_pass1 = "securepass1"; // merchant pass1 here // order properties $inv_id = 5; // shop's invoice number // (unique for shop's lifetime) $inv_desc = "desc"; // invoice desc $out_summ = "5.12"; // invoice summ // build CRC value $crc = md5("$mrh_login:$out_summ:$inv_id:$mrh_pass1"); // build URL $url = "https://auth.robokassa.ru/Merchant/Index.aspx?MrchLogin=$mrh_login&". "OutSum=$out_summ&InvId=$inv_id&Desc=$inv_desc&SignatureValue=$crc"; // print URL if you need echo "<a href='/ru/$url'>Payment link</a>";

Verification of notification (ResultURL)

// as a part of ResultURL script // your registration data $mrh_pass2 = "securepass2"; // merchant pass2 here // HTTP parameters: $out_summ = $_REQUEST["OutSum"]; $inv_id = $_REQUEST["InvId"]; $crc = $_REQUEST["SignatureValue"]; // build own CRC $my_crc = strtoupper(md5("$out_summ:$inv_id:$mrh_pass2")); if (strtoupper($my_crc) != strtoupper($crc)) { echo "bad sign\n"; exit(); } // print OK signature echo "OK$inv_id\n"; // perform some action (change order state to paid)

Verification of operation parameters ("cashier check") in SuccessURL script

// as a part of SuccessURL script // your registration data $mrh_pass1 = "securepass1"; // merchant pass1 here // HTTP parameters: $out_summ = $_REQUEST["OutSum"]; $inv_id = $_REQUEST["InvId"]; $crc = $_REQUEST["SignatureValue"]; $crc = strtoupper($crc); // force uppercase // build own CRC $my_crc = strtoupper(md5("$out_summ:$inv_id:$mrh_pass1")); if (strtoupper($my_crc) != strtoupper($crc)) { echo "bad sign\n"; exit(); } // you can check here, that resultURL was called // (for better security) // OK, payment proceeds echo "Thank you for using our service\n";

ASP.NET

URL for redirection of the customer to the service

using System; using System.Text; using System.Globalization; using System.Security.Cryptography; public partial class Init : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // your registration data string sMrchLogin = "test"; string sMrchPass1 = "securepass1"; // order properties decimal nOutSum = 5.12M; int nInvId = 5; string sDesc = "desc"; string sOutSum = nOutSum.ToString("0.00", CultureInfo.InvariantCulture); string sCrcBase = string.Format("{0}:{1}:{2}:{3}", sMrchLogin, sOutSum, nInvId, sMrchPass1); // build CRC value MD5CryptoServiceProvider md5 = new MD5CryptoServiceProvider(); byte[] bSignature = md5.ComputeHash(Encoding.ASCII.GetBytes(sCrcBase)); StringBuilder sbSignature = new StringBuilder(); foreach (byte b in bSignature) sbSignature.AppendFormat("{0:x2}", b); string sCrc = sbSignature.ToString(); // LinkButtonPay is System.Web.UI.WebControls.LinkButton; LinkButtonPay.Text = "Payment link"; // build URL LinkButtonPay.PostBackUrl = "https://auth.robokassa.ru/Merchant/Index.aspx?" + "MrchLogin=" + sMrchLogin + "&OutSum=" + sOutSum + "&InvId=" + nInvId + "&Desc=" + sDesc + "&SignatureValue=" + sCrc; } }

Verification of notification (ResultURL)

using System; using System.Web; using System.Text; using System.Globalization; using System.Security.Cryptography; public partial class Result : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // your registration data string sMrchPass2 = "securepass2"; // HTTP parameters string sOutSum = GetPrm("OutSum"); string sInvId = GetPrm("InvId"); string sCrc = GetPrm("SignatureValue"); string sCrcBase = string.Format("{0}:{1}:{2}", sOutSum, sInvId, sMrchPass2); // build own CRC MD5CryptoServiceProvider md5 = new MD5CryptoServiceProvider(); byte[] bSignature = md5.ComputeHash(Encoding.ASCII.GetBytes(sCrcBase)); StringBuilder sbSignature = new StringBuilder(); foreach (byte b in bSignature) sbSignature.AppendFormat("{0:x2}", b); string sMyCrc = sbSignature.ToString(); if (sMyCrc.ToUpper() != sCrc.ToUpper()) { Response.Write("bad sign"); return; } Response.Write(string.Format("OK{0}", sInvId)); // perform some action (change order state to paid) } private string GetPrm(string sName) { string sValue; sValue = HttpContext.Current.Request.Form[sName] as string; if (string.IsNullOrEmpty(sValue)) sValue = HttpContext.Current.Request.QueryString[sName] as string; if (string.IsNullOrEmpty(sValue)) sValue = String.Empty; return sValue; } }

Verification of operation parameters ("cashier check") in SuccessURL script

using System; using System.Web; using System.Text; using System.Globalization; using System.Security.Cryptography; public partial class Success : System.Web.UI.Page { protected void Page_Load(object sender, EventArgs e) { // your registration data string sMrchPass1 = "securepass1"; // HTTP parameters string sOutSum = GetPrm("OutSum"); string sInvId = GetPrm("InvId"); string sCrc = GetPrm("SignatureValue"); string sCrcBase = string.Format("{0}:{1}:{2}", sOutSum, sInvId, sMrchPass1); // build own CRC MD5CryptoServiceProvider md5 = new MD5CryptoServiceProvider(); byte[] bSignature = md5.ComputeHash(Encoding.ASCII.GetBytes(sCrcBase)); StringBuilder sbSignature = new StringBuilder(); foreach (byte b in bSignature) sbSignature.AppendFormat("{0:x2}", b); string sMyCrc = sbSignature.ToString(); if (sMyCrc.ToUpper() != sCrc.ToUpper()) { Response.Write("bad sign"); return; } // you can check here, that ResultURL was called // (for better security) // OK, payment proceeds Response.Write("Thank you for using our service"); } private string GetPrm(string sName) { string sValue; sValue = HttpContext.Current.Request.Form[sName] as string; if (string.IsNullOrEmpty(sValue)) sValue = HttpContext.Current.Request.QueryString[sName] as string; if (string.IsNullOrEmpty(sValue)) sValue = String.Empty; return sValue; } }