QIWI
Feedback
bss@qiwi.com
NAV Navbar

Protocol for QIWI Service Providers

The interaction between QIWI system and 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 Protocol, a provider should:

Provider's Interface Requirements

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

  1. Accept HTTPS requests from subnet IP-addresses:
    • 79.142.16.0/20
    • 91.232.230.0/23
  2. 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.
  3. Respond to QIWI request using XML format in UTF-8 encoding.
  4. Response time should not exceed 60 seconds, otherwise QIWI service would disconnect by timeout.
  5. 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).
  6. 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.

Payment Processing

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

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

Payment 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:

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.

There is a column indicating the fatal error (Fatality) in the list of error codes.

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.

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: service.someprv.ru: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: service.someprv.ru:8443

command=check&txn_id=1234567&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp
Parameter Condition 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 Optional Identifier of the specific service. Use it when the provider offers more than one service.
prv_id Optional Internal identifier of the provider in QIWI. It is used for consolidators.
data1, data2,…, dataN Optional Extra parameters for the provider
account1, account2,…, accountN Optional 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 Condition 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 Optional Comment for the operation
fields Optional Section with subscriber's information or operation data
fields.field1, …, fields.fieldN Optional Tags with information
fields.field1.type, …, fields.fieldN.type Optional 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 Optional 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 Optional 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: service.someprv.ru:8443

command=pay&txn_id=1234567&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: service.someprv.ru:8443

command=pay&txn_id=1234567&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp
Parameter Condition 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
account Required Client's identifier in the provider's system
sum Required Transaction amount
pay_type Optional Identifier of the specific service. Use it when the provider offers more than one service.
prv_id Optional Internal identifier of the provider in QIWI. It is used for consolidators.
data1, data2,…, dataN Optional Extra parameters for the provider
account1, account2,…, accountN Optional 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 Condition 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 Optional Comment for the operation
fields Optional Section with client's information or operation data
fields.field1, …, fields.fieldN Optional Tags with information
fields.field1.type, …, fields.fieldN.type Optional 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 Optional 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 Optional 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:

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:

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:

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