Request ID not specified. What is a unique payment identifier? How to find out the unique payment identifier? Example of a request to check the status of a subscriber's account and register a payment
The check is carried out to ensure that the invoice and subsequent payment can be processed correctly on the Project side.
With simplified integration, the user ID and order are checked twice: when going to the payment form and when choosing a payment method.
The project needs:
- User ID or order verification URL(specify in Technical Settings in your Personal Account);
- A handler capable of accepting and recognizing request parameters from the System and responding as the System expects.
If the ID verification after issuing an invoice fails, then the invoice will not be issued, and the user will be redirected to the payment error page specified by the project using the parameter return_url_fail or in the Technical Settings (if the page is not specified, a similar one on the System side is used). A parameter is automatically sent to the payment error page using the GET method err_msg with meaning "Such a character does not exist".
Request parameters from the System to the Project
The system sends the Project a request to the URL for checking the user ID or order specified in the Technical Settings in the Personal Account.
- transfer method - POST;
- encoding - UTF-8.
Parameter |
Parameter description |
Parameter format |
Required parameter |
|---|---|---|---|
| userid | User or order ID (equal to the parameter value nickname V ) | string(256) | Yes |
| userid_extra | Additional information required to make a payment or collect statistics on the Project side (equal to the parameter value nick_extra ) | string(500) | No |
| key |
Verification signature of the request. It is formed as a hash using the md5 algorithm from the concatenation of the following parameters:
|
md5(0userid0project secret) | Yes |
| amount | 0 | Yes | |
| paymentid | Checking the check request. Only accepts a zero value (amount = 0) | 0 | Yes |
| orderid | Payment ID in the Project accounting system (equal to the parameter value order_id V ) | varchar(64) | No |
Project Response Options
The System's request from the Project must receive a response.
The following rules are used to pass request parameters:
- format - XML;
- encoding - UTF-8.
Parameter |
Parameter description |
Parameter format |
Required parameter |
|---|---|---|---|
| code |
Request response code.
|
(case sensitive) |
Yes |
| comment | Decoding the response code to the request. Text examples:
|
string(400) | No |
Example response to a user ID or order verification request
YES
An example of a minimal System request handler when checking a user ID or order
//Generating a response function sendResponse($status, $message = "")( $response = ""."\n"; $response .= " ".$status.""."\n"; $response .= "
Unique payment identifier - what is it? What is it for? These are the most common questions that entrepreneurs ask when paying taxes at the bank, when a bank employee asks to indicate this causes confusion. Where can I find it, how can I get it, and can I do without it? Thus, a tool created to simplify the procedure resulted in new issues that needed to be clarified.
What is a unique identifier?
A unique payment identifier is a 20-digit code that must be specified when paying off tax debts. This makes it possible to easily and quickly pay taxes from your personal account on the tax service website. This approach greatly simplifies and speeds up the operation procedure. Payment occurs quickly, and therefore on time, which avoids delays, which means penalties and interest.
Using a unique identifier allows entrepreneurs, legal entities and individuals to pay taxes in a convenient way. But receiving and filling out tax documentation forms in this case has its own characteristics that must be taken into account. The problem also lies in the fact that the government information service itself has a complex, confusing structure that even an experienced user cannot always understand.
What is it for?
It is needed so that the Federal Tax Service knows when and from which person the money was received into the account. There are millions of users registered in GIS; it is difficult to determine from whom and for what purposes money is transferred. That is why, by order of the Ministry of Finance No. 107n dated November 12, 2013, the rules were changed, according to which a unique identifier for accrual payments appeared separately for taxes.
The tax service needs it in order to more effectively implement fiscal policy and identify persistent defaulters. Legal entities and individuals need it as the most convenient and fastest way to pay taxes. As a result, the government can control the actions of tax officials and stop cases when their actions exceed the powers delegated to them, which often happened in the past. Businessmen are less dependent on the will of the individual and suffer from illegal extortions. The number of inspections carried out has been reduced.
Who should indicate it?
Both ordinary citizens, entrepreneurs (individuals), and legal entities can indicate a unique payment identifier. This can be done when paying taxes directly in the information system account or through a bank. When transferring, you should take into account that payment through Sberbank has its own characteristics. They have their own special form, when filling it out, a unique identifier does not need to be specified. The UIN is indicated when paying taxes and state duties through the State Services service or a bank branch.
If an individual or legal entity fills out payment documents for the payment of taxes and fees, the payment deadline for which has not yet expired, then he may not enter a unique identifier, but insert a zero in the due date for entering the details. Although this method of filling out the line is permitted by law, when paying through a bank, the employee may require filling out the line with a 20-digit payment number and has the right to refuse to accept the payment. Therefore, it is important to know in which cases it must be indicated, and in which it is not necessary.
In what cases is it necessary to indicate it?
It should be noted that the identifier does not always need to be specified, but only in certain cases, which are described in the rules and regulations of the Bank of Russia (in particular, regulation No. 383-P). UIN - a unique identifier is indicated in two cases:
- If it was indicated by the recipient of the funds and provided to an individual or legal entity obligated to pay them in accordance with the terms of the agreement. In this case, the identifier is assigned automatically.
- When transferring funds to the tax authorities. An entrepreneur or individual fills out special fields (lines) of the payment slip in paper or electronic form. In this case, filling out causes some difficulties. After all, an entrepreneur does not always know his unique payment identifier number or where to get it.
In the second case, most taxpayers experience difficulties because they do not know where to get it and where to indicate it in the document. And incorrectly specified data leads to delays in payment, penalties and fines.
Where and how can I get an ID?
How can I find out information about the unique payment identifier, as well as whether the payment was accepted? You can check this both in your GIS personal account after registering in the system, and upon receiving a payment order in case of late payments. But this is an extreme case. The entrepreneur will know the number from the documents indicating the presence of a debt or fine to the tax authorities.
If there were no overdue payments, but you need to indicate the UIN, then you just need to send a request to the tax service to get a number.
How to fill it out correctly?
When taxpayers make payments to the budget system of the Russian Federation, they fill out a payment order. In addition to the unique identifier, the entrepreneur must indicate:
- BIC of the institution through which the payment will be made;
- name of the bank, its legal address;
- the current account from which the transfer will be made;
- type of payment (code);
- date of the operation.
The number is entered into the line of the unique payment identifier - 22 (field code). Do not fill out only if payment occurs on time. In this case, enter “0” (zero) in this line.
What to do if the document already contains a UIN?
Sometimes, especially when making payments through specialized information systems, when filling out an order electronically in the line (its code is 22), a unique payment identifier appears on its own. How should we feel about this? Is this considered an error if funds are deposited on time? In fact, there is no error. You can pay either by indicating the ID number or by entering “0” in the line. They just require you to indicate the identifier when payment is late, that is, at the request of the tax office.
Although it is possible to pay without restrictions, this approach is undesirable. An enterprise must distinguish between regular tax payments and those paid at the request of the tax authorities. This will help avoid confusion in reporting.
But even if it was not possible to find out and indicate the identifier in the order, this does not give the banks the right to refuse to accept it. The bank is obliged to accept and transfer funds, even if the UIP (unique payment identifier) is not specified. This rule is spelled out in official documents of the tax service. It clearly states that an individual or legal entity only needs to indicate their TIN and enter “0” in the line (code 22) of the unique payment identifier. In this case, the bank does not have the right to refuse to transfer the payment. But the entrepreneur must take into account that in the event of an error or delay, the bank is not responsible.
What does the code mean: decoding the identifier
The identifier is decrypted as follows:
- Numbers 1 to 3 indicate the code of the tax department to which the funds will be received.
- The number 4 indicates the type of payment. This place is always zero.
- Numbers from 5 to 19. Indicate the document code in the tax system. Each payer is assigned its own special code, based on the previous version of the document index.
- Digit 20. Its number determines which government agency is verifying the payment. Calculated taking into account the remaining 19 digits of the code.
The unique payment identifier is identical to the document index only if the index consists of 20 digits.
What happens if you don't specify it?
Using the UIN number, taxes and other payments to the budget are automatically recorded. Information about payments to the budget is transferred to a single database. If you enter the wrong code or do not specify it, the system will not recognize the payment and the money will not be transferred. This is fraught with such troubles as:
- the company will incur debt to the budget and funds;
- penalties will continue to accrue;
- you will need to clarify the payment and find out its fate;
- the money will arrive to the budget or funds with a delay.
If a businessman does not have or does not know a unique payment identifier where to get it, he can use the support service in GIS at any time, rather than wait for the tax authorities to take action. If an entrepreneur does not have access to the Internet and the State Services electronic system, he can send a regular letter to the nearest tax office or appear in person to receive an identifier.
What documents are needed to obtain an ID?
It all depends on the form in which the document will be drawn up and how to pay. If this is a paper document, then you must send a written request to the tax authority. In the letter, indicate your passport details, INN and SNILS number. A unique payment identifier will be sent in a response letter. If a legal entity or individual comes to the department in person to receive this information, then these documents must be with him. They are required to fill out forms.
To receive details electronically, you must first register in the unified information system on the State Services website, indicating the same data as with a written request. After this, a letter will be sent to your place of residence with an access key. And only after this can you make a request to obtain a unique identifier. Usually this service is provided within a few hours after the application. No documents are required.
As you can see, there is nothing complicated when using the identifier. It won't be difficult to recognize him. To do this, you don’t need to collect a bunch of documents or certificates. But taxes can be paid in a convenient form and at any time. If previously legal entities and individuals had to spend time and money to make tax payments, then with its help they can be paid without leaving home or office, without interrupting work.
- The interface must accept HTTPS requests from subnet IP addresses:
- 79.142.16.0, mask 255.255.240.0 (20)
- 91.232.230.0, mask 255.255.254.0 (23)
- The interface must process parameters passed by the system using the HTTP GET method.
- The interface must generate a response to the system in XML format in UTF-8 encoding.
- The exchange of information is carried out in the “request-response” mode, and the response speed should not exceed 60 seconds, otherwise the system breaks the connection due to a timeout.
- If the expected number of payments for the services of the connected provider is expected to be intensive (up to 10 payments per minute or more), it is necessary that the interface supports multi-threaded communication up to 10-15 simultaneous connections.
- The interface must accept requests via the HTTPS protocol on one of the following TCP ports: 80, 81, 443, 8008, 8080, 8081, 8090, 8443, 4433. The use of other ports is not allowed.
Basic principles of the interface
All requests are sent using the GET method, parameters are passed in the request path.
The transfer of payment information to the provider is carried out by the QIWI Wallet system in two stages - checking the subscriber’s status and directly making the payment. A preliminary stage of obtaining additional payment parameters from a provider that provides several services to the subscriber can also be added to inform the payer and add payment parameters of the payer’s choice.
The type of request is transmitted by the QIWI Wallet system in the command variable - a string that takes the values check, pay or getInfo:
Query parameters
All parameters are required in the queries in which they are used.
| Parameter | Format | Description | In what queries is it used? |
|---|---|---|---|
| txn_id | Integer up to 20 characters long | Unique payment identifier in the QIWI system. This identifier is used to resolve controversial issues. | check, pay |
| sum | A fractional number accurate to hundredths is used as a separator. (dot). If the sum represents an integer, then it is still supplemented with a dot and zeros, for example - 152.00. | Amount of payment | check, pay |
| ccy | Alpha-3 ISO 4217 currency code | Payment currency | check, pay |
| txn_date | YYYYMMDDHHMMSS | Payment date (the payment date in the system means the date the request was received from the client). Based on this date, further reconciliation of mutual settlements between QIWI Wallet and the provider is carried out. For example, the client sent a request to the QIWI Wallet system on 12/31/2010 at 23:59:59, and the QIWI Wallet system sent its request to the provider on 01/01/2011 at 00:00:05. This can lead to a payment reconciliation issue if the provider's system places the transaction in the next billing period. To avoid such problems, QIWI Wallet provides the provider with the original payment date. |
pay |
| account | A string containing letters, numbers and special characters, up to 200 characters long | Subscriber ID. The provider identifies its subscriber by a unique identifier (personal account number, phone number, login, etc.). Before being sent to the provider, the identifier is validated according to a regular expression that . | check, pay, getInfo |
| extra | Acceptable numbers are numbers (0-9), underscores (_) and lowercase Latin letters (a-z) | Additional payment details (extra fields). These parameters can be used if the payment cannot be made without additional data (one user ID in the provider’s system is not enough). For example, the user ID is a credit card number, but to make a payment you also need to specify the card's expiration date. The list of required fields to be transferred to the provider must be indicated in . |
check, pay |
| prvId | Integer | Service identifier in the provider's common system. | getInfo |
| parameter_name | The format of the name and value of the parameters is specified by the provider in . | Additional parameters for subscriber identification | getInfo |
To support extensibility and maintain the functionality of the provider's service during the period when various functions provided for by the protocol are enabled (for example, enabling the transfer of new payment details), it is assumed that the provider does not prevent the appearance of new HTTP parameters in the request.
It is guaranteed that the appearance of new parameters in a request will not lead to the need to change request processing on the part of the provider, unless such a change in logic has been agreed upon with the provider.
Response Format
The provider must return the response to requests to the system in XML format. The general structure of the answer is shown in the tab on the right.
If any of the requests to the provider fails, the provider returns an error code in accordance with .
The provider's information system should not contain two successfully completed payments with the same txn_id number. If the system resends a request with the txn_id identifier already existing in the provider’s information system, then the provider must return the result of processing the previous request.
The response may contain the following tags:
For example, there is a situation: the client sent a request to the system on 12/31/2010 at 23:59:59. Taking into account the delay in processing data and sending information via communication channels, the payment will be received by the provider on 01/01/2011 00:00:05 and, accordingly, will be taken into account in the provider’s system in another reporting period. To avoid problems with different reporting periods when conducting reconciliations, it is necessary that the provider returns the date on which accounting is carried out in its system.
Example of a request to check the status of a subscriber's account and register a payment
Example conditions:
The provider's payment application payment_app is located at yourservice.prv.ru, the server supports HTTPS connections on port 8443.
To check the subscriber's status, the QIWI Wallet system generates a request (see the tab on the right).
GET /payment_app?command=check&txn_id=1234567& account=4957835959&sum=10.45&ccy=RUBThe request contains parameters:
- command=check – identifier of the request to check the subscriber’s status;
Successful response from the provider (see tab on the right).
Returning result=0 to a check request indicates that the subscriber’s personal account with the corresponding number in the account field can be replenished by the amount specified in the request in the sum field. After successfully checking the subscriber's account status, the system proceeds to generating and sending a request to top up the balance (pay request).
Example of a request to top up a personal account
Example conditions:
To confirm the payment, the QIWI Wallet system generates a request (see tab on the right).
GET /payment_app?command=pay&txn_id=1234567& txn_date=20110815120133&account=4957835959&sum=10.45&ccy=RUB HTTP / 1.1 Host : yourservice.prv.ru:8443 Provider responseThe request contains parameters:
- command=pay – identifier of the request to top up the subscriber’s balance;
- txn_id=1234567 – internal payment number in the QIWI system;
- txn_date=20090815120133 – date of registration of the payment in the QIWI system;
- account=4957835959 – subscriber identifier in the provider’s information system;
- sum=10.45 – amount to be credited to the subscriber’s personal account;
- ccy=RUB – currency of the amount credited to the subscriber’s personal account.
By returning result=0 to the pay request, the provider reports the successful completion of the balance replenishment operation. The system completes processing this transaction.
The optional comment field contains a service comment.
Example of a request for additional payment data
Example conditions:
The provider's payment application payment_app is located at yourservice.prv.ru, the server supports HTTPS connections on port 8443.
To obtain additional payment data, the QIWI Wallet system generates a request (see the tab on the right).
GET /payment_app?command=getInfo&prvId=12345& account=4957835959&name1=%26%30AB&name2=0 HTTP / 1.1 Host : yourservice.prv.ru:8443 Provider responseThe request contains parameters:
- command=getInfo – identifier request to obtain additional payment data for the subscriber;
- prvId=12345 – identifier for identifying the provider service;
- account=4957835959 – subscriber identifier in the provider’s information system;
- name1, name2 – additional subscriber identifiers.
See the tab on the right for the provider's response.
Returning result=0 to a getInfo request indicates that the request was completed successfully and additional data to be displayed to the subscriber was received.
The optional comment field contains a service comment.
Daily reconciliation
Before 10:00 Moscow time, the system generates and sends to the specified address an electronic register of accepted payments for the previous day.
The register has the following structure:
Transaction date (Moscow);Report date;Type;Transaction number;Transaction currency ID;Transaction amount;Merchant"s comment;Merchant"s transaction/invoice number;Invoice date of issue;QW ID;Account;Refund ID
The fields are separated by a sign; , the fractional part of the amount is separated by a dot, the date/time is Moscow, the line feed can consist of either the characters x0D x0A or simply x0D.
For example:
31.02.2005 00:04:00;31.02.2005
00:00:00;Payment;3464968222;USD;5.00;;;;;0957835959;;
02/31/2005 00:04:00;02/31/2005 00:00:00;Payment;3464968912;RUB;10.34;;;;; [email protected];;
02/31/2005 00:11:00;02/31/2005 00:00:00;Payment;3464974548;EUR;4.72;;;;;ABC-12345;;
The system includes only successfully completed payments in the register.
Payments that were received both through online messaging and in the register are considered confirmed.
If the register does not contain payments that were made in the provider’s database, or contains payments that are not in the provider’s database, or if the register has not been received, you must contact the QIWI contact person specified in the agreement before 12:00 to clarify the situation and make a decision.
Additional request authorization options
In the connection application, the provider can specify an identifier (login) and a secret password for it, used for authorization when making requests from QIWI.
This authorization data is transmitted according to standard basic authentication rules for HTTP(S) requests. An Authorization HTTP header is added to the request. The header contains the string Basic (with a space at the end) and the “login:password” pair encoded in BASE64:
Authorization: Basic ***
BASE64("Login:Password") = "***"
Application for connection (sample)
List of exit codes
When processing requests from the system, the provider must match all errors occurring in its application with the list below and return the corresponding codes in the element.
The + sign in the “fatality” column indicates that the error is fatal. For the QIWI Wallet system, a fatal error means that resending a request with the same parameters will lead to a 100% repetition of the same error - therefore, the system stops processing the client request and completes it with an error.
A non-fatal error means to the system that repeating the request with the same parameters after a certain period of time will probably lead to success. The system will repeat requests that fail with a non-fatal error, continually increasing the interval, until the operation succeeds or fails, or until the request's 24-hour lifetime expires.
Lack of connection to the provider's server is a non-fatal error.
The absence of an element in the response (incorrect XML, Service temporarily unavailable page, etc.) is also a non-fatal error.
| Code |
|---|
General information
Description of input parameters
Description of output parameters
or
Output: XML document according to the scheme WS_ULIPOTVID_2_311_09_04_02_01.XSD
Complex type parameters are described in the Appendix “Description of General Data Structures” (in paragraphs 10, 6, 9).
Return codes
| № | Return code | Return code description | Conditions of occurrence | A comment |
| 1 | 01 | The requested information was not found | Occurs provided that information about the legal entity is not found in the Unified State Register of Legal Entities | |
| 2 | 51 | Request accepted for processing | Occurs when a request is successfully accepted for processing | |
| 3 | 52 | The answer is not ready | Occurs when a response to a request successfully accepted for processing is not ready | Used for asynchronous request |
| 4 | 53 | Information regarding a legal entity/individual entrepreneur cannot be provided electronically | Occurs when it is impossible to generate a response to a request in electronic form. | |
| 5 | 82 | Format-logical control error | Occurs when the document (request) does not match the xsd schema | Reserve, may not be used |
| 6 | 83 | There is no request with the specified request ID and type of information requested from this authority | Occurs in a situation where the request for a result of a request for an extract from a legal entity indicates an incorrect (unknown) request identifier and (or) a request with such an identifier was not received from this authority | Used for an asynchronous request (when receiving the result of a request for an extract from a legal entity) |
| 9 | 99 | System error | Occurs when there are internal errors in the IS software of the Federal Tax Service of Russia |
Test cases
Response to a request to receive the result of a request to obtain an extract from a legal entity, in case the request has not yet been processed
Response to a request to receive the result of a request to obtain an extract from a legal entity with return code 53
Response to a request for the result of a request for an extract from a legal entity with an error (the processing code for which is not reserved)
(attribute values change and)
| |
Note: The conditions for this error to occur in the test environment were artificially triggered. This example describes the general logic and structure of an error response. When testing on a production environment, returning exactly the same response without providing the necessary conditions is not possible.
