Protocol for QIWI Service Providers

The interaction between QIWI system and a Service provider (hereinafter referred to as the provider) is built in the "request-response" mode, where the initiator of the request is always the QIWI system, and the response always comes from the provider.

Each payment in the QIWI system has a unique identifier, which is transmitted in each request. This identifier further reconciles mutual settlements and resolves contentious issues.

To connect with the Interface, a provider should:

Implement the requirements for the interface
Comply with rules for processing requests
implement payment process.

Provider's Interface Requirements

Provider's application interface has to comply with the following requirements:

Accept parameters using HTTP GET, HTTP POST methods. Parameters are placed either in the HTTP GET request's path or in HTTP POST request's body as URL-encoded string.
Respond to QIWI request using XML format in UTF-8 encoding.
Response time should not exceed 60 seconds, otherwise QIWI service would disconnect by timeout.
Ability to support multi-thread communication up to 10-15 simultaneous connections, when the planning payments flow for provider's services is high (i.e. more than 10 payments per minute).
Interface should accept requests by HTTPS protocol on one of the following TCP-ports: 80, 81, 443, 8008, 8080, 8081, 8090, 8443, 4433. Using other ports is not allowed.
Use certificates for secure interaction with QIWI services.

SSL certificate (SSL – Secure Socket Layer) *.qiwi.com is used for encrypted connections between partner and QIWI services to avoid open transfer of the personal and payment data.

As SSL certificate has an expiration date you should monitor its validity. QIWI updates the certificate every year.

Download QIWI public certificate from https://static.qiwi.com/ru/files/ssl_certificate_QIWI.zip to use in client software.
Interface should accept requests only from QIWI subnet IP-addresses:

79.142.16.0/20
195.189.100.0/22
91.232.230.0/23
91.213.51.0/24

Payment Processing

In the process of payment, the QIWI system is consistently following steps:

Check the status of the abonent in the information system of the provider.
Register the payment.

The provider needs to implement processing requests on each of these steps.

Sequence diagram for the payment process:

sequenceDiagram participant qiwi as QIWI System participant prv as Provider qiwi->>prv:Check the status of the subscriber ("check" request) Note right of qiwi: command=check, txn_id, account, sum, optional fields prv-->>qiwi:Response with result Note left of prv: osmp_txn_id, result, optional fields qiwi->>prv:Register the payment ("pay" request) Note right of qiwi: command=pay, txn_id, txn_date, account, sum, optional fields prv-->>qiwi:Response with result Note left of prv: osmp_txn_id, prv_txn, sum, result, optional fields

Request Processing Rules

When processing requests from the QIWI system, the provider must perform the required operation and then respond with the data (if requested) and the operation result code in XML document format. Provider should compare all errors appearing in its application during the request processing according to the list of error codes and return corresponding codes in <result> XML tag of the response.

There are fatal and non-fatal error codes:

A fatal error means that resubmitting a request with the same parameters will result in a 100% repetition of the same error. Therefore, on receiving a fatal error the QIWI system stops processing the request and finishes it with error.
A non-fatal error means for the QIWI system that repeating a query with the same parameters after a certain period of time may be successful. When a non-fatal error is received, the QIWI system will repeat the requests, increasing the interval until the operation is successful or fatal, or until the payment in the QIWI system expires (24 hours).

For example, no connection to the provider's server is a non-fatal error. The absence of the <result> tag in the answer is a fatal error.

The list of error codes has a column indicating the fatal error (Fatality).

Check the status of the subscriber

On receiving the request, the provider must check the presence of a subscriber with the specified ID in its database and perform internal checks of the ID and the amount of payment in accordance with the accepted logic of replenishment of personal accounts through payment systems.

The provider's database must not contain two successful payments with the same payment ID (txn_id payment ID in QIWI system). If you receive a request with a txn_id already in the provider's database, the provider must return the result of processing the previous request.

Request parameters

Request example

POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:8443

command=check&txn_id=1234567&account=4950001111&sum=10.45

Request with extra parameters

POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:8443

command=check&txn_id=1234567&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp

Parameter	Description
command	Required. Identification of the type of request: check the subscriber's account. Always `check`
txn_id	Required. Payment identifier in QIWI system
account	Required. Subscriber's identifier in the provider's database
sum	Required. Operation amount
pay_type	Identifier of the specific service. Use it when the provider offers more than one service.
prv_id	Internal identifier of the provider in QIWI. It is used for consolidators.
data1, data2,…, dataN	Extra parameters for the provider
account1, account2,…, accountN	Extra accounts of the client in the provider's system (if client has multiple accounts)

Response parameters

Response example

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <osmp_txn_id>1234567</osmp_txn_id>
    <result>0</result>
    <comment>Some comment</comment>
</response>

Response example with extra parameters

<?xml version=”1.0” encoding="UTF-8"?>
<response>
         <osmp_txn_id>1234567</osmp_txn_id>
         <result>0</result>
         <fields>
               <field1 name="name1" type="disp">value1</field1>
               <field2 name="name2" type="disp">value2</field2>
               <field3 name="name3" type="prt-data">value3</field3>
         </fields>
</response>

In response, the provider's interface must return an XML document containing the <response> block with the following XML tags:

Tag	Description
osmp_txn_id	Required. QIWI system's transaction identifier, that is `txn_id` from the original request
result	Required. Operation result code (`result=0` if payment is possible)
comment	Comment for the operation
fields	Section with subscriber's information or operation data
fields.field1, …, fields.fieldN	Tags with information
fields.field1.type, …, fields.fieldN.type	Information data type. The following types are possible: `disp` – information to show to the customer when making a payment (by default, if the type is not specified); `info` – information to save in the QIWI system `prt-data` - text to print on the receipt when making a payment (used only for payments from SSK)
fields.field1.name, …, fields.fieldN.name	The name of the information parameter. If not specified, the name `disp1`,.., `dispN` (according to the order number of the `fieldN` tag) is assigned
pay_id	Information about the provider's gateway, which will register the payment. Information about which gateways are available for selection is updated when tested with the QIWI system.

Register the payment

On getting the request, provider must replenish the client's balance in its system.

Request parameters

Request example

POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:8443

command=pay&txn_id=1234567&txn_date=20220815120133&account=4950001111&sum=10.45

Request with extra fields

POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:8443

command=pay&txn_id=1234567&txn_date=20220815120133&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp

Parameter	Description
command	Required. Request type: replenish the client's balance. Always `pay`
txn_id	Required. Payment identifier in the QIWI system
txn_date	Required. Date of the transaction with `YYYYMMDDHHMMSS` format
account	Required. Client's identifier in the provider's system
sum	Required. Transaction amount
pay_type	Identifier of the specific service. Use it when the provider offers more than one service.
prv_id	Internal identifier of the provider in QIWI. It is used for consolidators.
data1, data2,…, dataN	Extra parameters for the provider
account1, account2,…, accountN	Extra accounts of the client in the provider's system (if client has multiple accounts)

Response parameters

Response example

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <osmp_txn_id>1234567</osmp_txn_id>
    <prv_txn>123</prv_txn>
    <sum>10.00</sum>
    <result>0</result>
</response>

Response example with extra parameters

<?xml version=”1.0” encoding="UTF-8"?>
<response>
         <osmp_txn_id>1234567</osmp_txn_id>
         <prv_txn>2016</prv_txn>
         <sum>1.00</sum>
         <result>0</result>
         <fields>
               <field1 name="name1" type="disp">value1</field1>
               <field2 name="name2" type="disp">value2</field2>
               <field3 name="name3" type="prt-data">value3</field3>
         </fields>
</response>

In response, the provider's interface must return an XML document containing the <response> element with the following XML tags:

Tag	Description
osmp_txn_id	Required. QIWI system's transaction identifier, that is `txn_id` from the original request
prv_txn	Required. Unique ID of the replenishment operation in the provider's system
sum	Required. Payment amount transferred to the provider
result	Required. Operation result code (`result=0` if payment is successfully registered)
comment	Comment for the operation
fields	Section with client's information or operation data
fields.field1, …, fields.fieldN	Tags with information
fields.field1.type, …, fields.fieldN.type	Information data type. The following types are possible: `disp` – information to show to the customer when making a payment (by default, if the type is not specified); `info` – information to save in the QIWI system `prt-data` - text to print on the receipt when making a payment (used only for payments from SSK)
fields.field1.name, …, fields.fieldN.name	The name of the information parameter. If not specified, the name `disp1`,.., `dispN` (according to the order number of the `fieldN` tag) is assigned
pay_id	Information about the provider's gateway, which will register the payment. Information about which gateways are available for selection is updated when tested with the QIWI system.

Daily Reconciliation

The QIWI system generates and sends payments list processed during the day before to the certain address specified in provider's configuration in the QIWI system next day at 10am on Moscow time.

Payments list is a plain text file which has the following structure:

The first line is the headline:

<email address where report will be sent>
The second and subsequent lines contain payments data:

<txn_id> <date> <time> <subscriber's identifier> <sum>
The last line contains total amount and number of payments in the registry:

Total: <number of payments> <amount of payments>

Fields on each line are separated by tab symbol. Decimals are point separated. Time/date are in Moscow time zone. Line feed symbols might be x0D x0A as well as just x0D.

Example of lines with data:

test@osmp.ru

12345678 20.08.2021 12:13:14 0957000059 123.45

12345678 20.08.2021 13:22:34 8002000059 0.01

12345678 20.08.2021 14:55:11 9161234567 123.01

12345689 20.08.2021 14:55:12 0732123456 1000.00

Total: 4 1246.47

The QIWI system includes only successful payments into the payments list.

Payments are treated as confirmed if they are received both in online requests and in the payments' list.

You need to contact support person in QIWI specified in the agreement until 12:00 pm to clarify the situation and make a decision, in the following cases:

when there are payments not registered in the provider's system
when there are no payments processed in the provider's system
when the payments registry not yet available at 10:00 of the day.

Authorization Methods

To authorize requests, provider may set identifier (login) and corresponding secret password to use in requests from QIWI side. Please specify those in the initial application for QIWI.

The login and password are used in standard Basic-authorization of the requests:

HTTP header Authorization is added.
In the header there are string Basic (ending with space) plus BASE64-encoded "login:password" string:

Authorization: Basic ***

Here:

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

Requests authorization by client SSL certificate is also supported. Please indicate the need for such authorization in the initial application for QIWI.

Error Codes

Code	Description	Fatality
0	ОК	No
1	Temporary error. Please repeat your request later	No
4	Wrong subscriber's identifier format	Yes
5	The subscriber's ID is not found (Wrong number)	Yes
7	Payment accepting forbidden by provider	Yes
8	Payment accepting forbidden because of technical problems	Yes
79	Subscribers account is not active	Yes
90	Payments processing is not finished	No
241	The amount is too small	Yes
242	The amount is too large	Yes
243	Impossible to check account status	Yes
300	Other error of the provider	No