Verification is carried out in order to make sure that the invoice and subsequent payment can be correctly processed on the side of the Project.

With simplified integration, the user ID and the order are verified twice: when switching to a payment form and when choosing a payment method.

The project needs:

• User ID or Order Verification URL(specify in the Technical Settings in the Personal Account);
• A handler capable of accepting and recognizing the parameters of a request from the System and responding as the System expects.

If the verification of the identifier after issuing the invoice ended with an error, 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 page is used on the System side). To the payment error page using the GET method the parameter is automatically sent err_msg with the meaning "This character does not exist.".

Request parameters from the System to the Project

The system sends a request to the Project for the URL for checking the identifier or user order specified in the Technical Settings in the Personal Account.

• transfer method - POST;
• encoding - UTF-8.

Parameter	Parameter description	Parameter format	Mandatory parameter
userid	User or order identifier (equal to the parameter value nickname v )	string (256)	Yes
userid_extra	Additional information required for making a payment or collecting statistics on the Project side (equal to the value of the parameter nick_extra )	string (500)	No
key	Verification signature of the request. It is formed as a hash according to the md5 algorithm from the concatenation of the following parameters: parameter value userid, project secret key	md5 (0userid0 project secret)	Yes
amount		0	Yes
paymentid	Checking the check request. Accepts only zero (amount = 0)	0	Yes
orderid	Payment ID in the accounting system of the Project (equal to the value of the parameter order_id v )	varchar (64)	No

Project response parameters

The Project should receive a response to the System's request.

The following rules are used to pass query parameters:

• format - XML;
• encoding - UTF-8.

Parameter	Parameter description	Parameter format	Mandatory parameter
code	Request response code. YES- the identifier exists. NO- identifier does not exist	(case sensitive)	Yes
comment	Decoding of the request response code. Examples of text: validation for the userid parameter failed; validation for the orderid parameter failed; validation for the key parameter failed	string (400)	No

Example of a response to a request to verify a user ID or order

YES

An example of a minimal system request handler when checking a user or order identifier

// Generate a response function sendResponse ($ status, $ message = "") ($ response = ""." \ n "; $ response. =" "." \ n "; $ response. =" ". $ status.""." \ n "; $ response. =" ". $ message.""." \ n "; $ response. =""; die ($ response);) // Check if a user ID or order exists function checkUser ($ userID) ($ sql =" SELECT login FROM users WHERE usr_id = ".intval ($ userID); $ query = mysql_query ($ sql ); if (mysql_error ()) (return FALSE;) if (mysql_num_rows ($ query) == 0) (return FALSE;) return TRUE;) $ secretKey = "IT \" S_A_PROJECT_SECRET_WORD "; $ projectHash = md5 ($ _ POST ["amount"]. $ _ POST ["userid"]. $ _ POST ["paymentid"]. $ secretKey); if ($ projectHash! = $ _POST ["key"]) (sendResponse ("NO", "The verification signature of the request is invalid.");) if (floatval ($ _ POST ["amount"]) == 0 && intval ($ _POST ["paymentid"]) == 0) (// Request to check the user ID or order if (checkUser ($ _ POST ["userid"])) (sendResponse ("YES", "ID exists");) else ( sendResponse ("NO", "ID not found");))

General information

Description of input parameters

Input data: XML document according to the scheme WS_ULIPZAPRID_2_311_11_04_02 _01_01.XSD

1. Description of the output parameters

Output: XML document according to the schema WS_OTVVIPULXSD_2_311_14_04_02_01.XSD

or

Output: XML document according to the WS_ULIPOTVID_2_311_09_04_02_01.XSD schema

Complex type parameters are described in the Appendix "Description of General Data Structures" (in clauses 10, 6, 9).

1. 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 received for processing
3	52	The answer is not ready	Occurs when a response is not ready for a request successfully accepted for processing	Used when making an asynchronous request
4	53	Information regarding a legal entity / individual entrepreneur cannot be provided to in electronic format	Occurs when it is impossible to form 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 the type of requested information from this authority	Occurs in a situation when an incorrect (unknown) request identifier is indicated in a request for obtaining a result for a statement of a legal entity statement and (or) a request with such an identifier has not been received from this authority	Used with an asynchronous request (when receiving the result of a statement request for a legal entity)
9	99	System error	Occurs when there are internal errors in the software of the IS FTS of Russia

1. Test cases

Request for obtaining the result of a request for obtaining a statement of legal entity

Response to a request to receive the result of a request for a statement of legal entity, in case the request has not yet been processed

Response to a request to receive the result of a request for a statement of legal entity with a return code 53

Response to a request to receive the result of a request for a statement of legal entity with an error (the processing code of which is not reserved)
(attribute values ​​change and)

Note: The conditions for this error in the test environment were artificially triggered. This example describes the general logic and structure of the error response. When testing on a productive environment, returning exactly the same response without providing the necessary conditions is not possible.

1. The interface must accept requests over HTTPS from the IP addresses of the subnets:
   • 79.142.16.0, mask 255.255.240.0 (20)
   • 91.232.230.0, mask 255.255.254.0 (23)
2. The interface must process parameters passed by the system using the HTTP GET method.
3. The interface must form a response to the system in XML format in UTF-8 encoding.
4. The exchange of information is carried out in the "request-response" mode, while the response rate should not exceed 60 seconds, otherwise the system terminates the connection by timeout.
5. If the expected number of payments for the services of the connected provider is expected to be intense (up to 10 payments per minute or more), the interface must support multi-threaded communication up to 10-15 simultaneous connections.
6. The interface must accept requests via HTTPS on one of the following TCP ports: 80, 81, 443, 8008, 8080, 8081, 8090, 8443, 4433. Using other ports is not allowed.

Basic principles of the interface

All requests are passed by the GET method, parameters are passed in the request path.

The transfer of information about the payment to the provider is carried out by the QIWI Wallet system in two stages - checking the status of the subscriber and directly making the payment. A preliminary stage of obtaining additional payment parameters from a provider providing the subscriber with several services can also be added to inform the payer and add payment parameters at 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 which queries is used
txn_id	Integer up to 20 characters	Unique identifier of the payment in the QIWI system. This identifier is used to resolve controversial issues.	check, pay
sum	Fractional number accurate to hundredths, used as a separator. (point). If the sum represents an integer, then it is still padded with a dot and zeros, for example - 152.00.	Amount of payment	check, pay
ccy	Currency Code Alpha-3 ISO 4217	Payment currency	check, pay
txn_date	YYYYMMDDHHMMSS	Date of payment (the date of payment in the system means the date of receipt of the request from the client). By this date, further reconciliation of settlements between QIWI Wallet and the provider is carried out. For example, a 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 problem of reconciliation of payments 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 against the regular expression that.	check, pay, getInfo
extra	Allowed are numbers (0-9), underscore (_) 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, your user ID is your credit card number, but you also need to specify the card's expiration date to make a payment. The list of required fields for transmission to the provider must be specified in.	check, pay
prvId	Integer	Service ID in common system provider.	getInfo
parameter_name	The format of the name and value of the parameters is specified by the provider in the.	Additional parameters for subscriber identification	getInfo

To support the extensibility and maintain the service provider's serviceability during the period when various functions provided by the protocol are enabled (for example, enabling the transfer of new payment details), it is assumed that the provider does not prevent new HTTP parameters from appearing in the request.

It is guaranteed that the appearance of new parameters in the request will not lead to the need to change the processing of requests by the provider, unless such a change in logic has been agreed with the provider.

Response format

The provider must return the response to the requests to the system in XML format. The general structure of the response is shown in the tab on the right.

123323498 12369Bdkjh9 100.00 643 2012-04-05T12: 00: 07 0

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 successful payments with the same txn_id number. If the system re-sends a request with the txn_id identifier already existing in the provider's information system, the provider must return the result of processing the previous request.

The following tags may be present in the response:

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 through communication channels, the provider will receive the payment on 01/01/2011 00:00:05 and, accordingly, will be recorded in the provider's system in another reporting period. To avoid problems with different reporting periods when reconciling, it is necessary that the provider returns the date on which accounting is made in its system.

An 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 = RUB 1234567 2016AB 10.45 RUB 0 OK

The request contains parameters:

• command = check - request identifier for checking the subscriber's status;

Successful response from the provider (see tab on the right).

Returning result = 0 to the check request indicates that the personal account of the subscriber with the corresponding number in the account field can be replenished with the amount specified in the request in the sum field. After successful verification of the subscriber's account status, the system proceeds to the formation and sending of a request for replenishment of the balance (pay request).

Example of a request to replenish a personal account

Example conditions:

To confirm the payment, the QIWI Wallet system generates a request (see the 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 response 1234567 2016AB 10.45 RUB 0 OK 2011-08-15T12: 06: 45

The request contains parameters:

• command = pay - request identifier for replenishing the subscriber's balance;
• txn_id = 1234567 - internal payment number in the QIWI system;
• txn_date = 20090815120133 - payment posting date 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 - the currency of the amount credited to the subscriber's personal account.

Returning result = 0 for the pay request, the provider informs about the successful completion of the balance replenishment operation. The system completely completes the processing of this transaction.

The optional comment field contains a service comment.

Example of a request to receive 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 response account1 term2 0 OK

The request contains parameters:

• command = getInfo - identifier of the request to receive additional payment data for the subscriber;
• prvId = 12345 - identifier for identifying the service provider;
• 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 answer.

Returning result = 0 to the getInfo request indicates that the request was completed successfully and additional data to display to the subscriber has been received.

The optional comment field contains a service comment.

Daily reconciliation

Until 10:00 Moscow time, the system generates and sends to the specified address an electronic register of payments received for the previous day.

The registry 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

;; Payment; ;;;;;;;;

;; Payment; ;;;;;;;;

The fields are separated by a sign; , the fractional part of the sum is separated by a dot, date / time - Moscow, line feed can consist of either the characters x0D x0A or just 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 successful payments in the register.

Confirmed payments are considered payments that came both in the online exchange of messages and in the register.

If the register does not contain payments that have been made in the provider's database, or contains payments that are not in the provider's database, or if the register is not received, you must contact the QIWI contact person specified in the contract by 12:00 to clarify the situation and make a decision.

Additional options for authorizing requests

In the application for connection, the provider can set an identifier (login) and a secret password to it, which are used for authorization when making requests from QIWI.

This authorization data is transmitted by standard rules basic authentication for HTTP (S) requests. The Authorization HTTP header is appended to the request. The header contains the Basic line (with a space at the end) and the “login: password” pair, encoded in BASE64:

Authorization: Basic ***

BASE64 ("Login: Password") = "***"

Connection application (sample)

List of completion codes

When processing requests from the system, the provider must match all errors that occur in its application with the list below and return the corresponding codes in the element.

The + sign in the fatal column indicates a fatal error sign. For the QIWI Wallet system, a fatal error means that resending a request with the same parameters will result in a 100% repetition of the same error - therefore, the system stops processing the client request and ends it with an error.

A non-fatal error means for the system that repeating a request with the same parameters after a certain period of time will possibly lead to success. The system will retry requests that fail with a non-fatal error, continuously increasing the interval until the operation succeeds or fails, or until the request expires - 24 hours.

Failure to communicate with the provider's server is a non-fatal error.

Missing an element in the response (invalid XML, Service temporarily unavailable page, etc.) is also a non-fatal error.

Code