Unified Interface for Information Exchange

The interface is designed to exchange information with a credit institution (hereinafter referred to as the provider) connected as a provider to QIWI.

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 combination of unique identifiers transmitted in each request:

sysid — payment system code;
sysno — integer up to 24 digits.

Combination of these identifier further reconciles mutual settlements and resolves contentious issues.

To connect with the Interface, a provider should:

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

See also the recommendations for integration with the QIWI interface:

Protocol Implementation Guidelines
Testing Guidelines
Frequently Asked Questions

Requirements for the Provider Interface

The interface should handle HTTP GET, HTTP POST requests over HTTP or HTTPS protocol.
The interface must generate a response to the request in XML format in UTF-8 encoding.
The response speed should not exceed 60 seconds, otherwise the QIWI service terminates the connection due to a timeout.
If the estimated number of payments for the services of the connected provider is expected to be up to 10 payments per minute or more, it is necessary that the interface supports multithreaded communication of up to 10-15 simultaneous connections.
The interface must accept requests from the IP addresses of QIWI subnet:

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

Request Processing Rules

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

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 fails to complete it.
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, incorrect XML document, "Service temporarily unavailable" page are fatal errors.

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

Payment Processing

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

Payment authorization.
Payment registration.

The provider must implement the processing of requests at each of these steps.

Protocol includes two additional methods to extend business scenario:

Obtaining additional information from the provider.
Cancellation of previously submitted request.

Implementation of these methods is optional.

Obtaining Additional Parameters for the Payment

The purpose of the request is to verify the Client's ID and obtain additional information about the Client. Upon receiving the request, the provider:

checks the presence of the Client with the specified identifier in the provider's information system;
returns additional information to be shown to the payer when making a payment.

The request is perfomed before the payment authorization.

The provider's database must not contain two successful payments with the same sysid and sysno identifiers. If you receive a request with a sysid and sysno couple already in the provider's database, the provider must return the result of processing the previous request.

Request parameters

Request for obtaining additional parameters

<?xml version="1.0" encoding="UTF-8"?>
<request command="getinfo">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <doctime>20211031124845</doctime>
    <mesid>4444</mesid>
    <docno/>
    <rem_key/>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid></keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>

Parameter	Format	Required	Description
command	`getinfo`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
auth		✓	Authorization information
login	varchar2(30)	✓	Login
psw	varchar2(30)	✓	Password
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
mesid	varchar2(5)	✓	Payment type
docno	varchar2(20)		Document number
rem_key	varchar2(30)	✓	Client identifier in the provider's information system
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

Response parameters

Response for obtaining additional parameters

<?xml version="1.0" encoding="UTF-8"?>
<response command="getinfo">
  <verno>342</verno>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
    </id>
    <mesid>4444</mesid>
    <docno></docno>
    <rem_name></rem_name>
    <rem_name2></rem_name2>
    <rem_name3></rem_name3>
    <rem_address></rem_address>
    <rem_key></rem_key>
    <result></result>
    <comment></comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
      <fieldN></fieldN>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid></keyid>
    <encrypt></encrypt>
  </crypt>
</response>

The provider must respond with XML document having root <response> tag and the following tags:

Parameter	Format	Required	Description
command	`getinfo`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
mesid	varchar2(5)	✓	Payment type
docno	varchar2(20)		Document number
rem_name	varchar2(254)		Payer last name
rem_name2	varchar2(254)		Payer first name
rem_name3	varchar2(254)		Payer surname
rem_address	varchar2(254)		Payer address
rem_key	varchar2(30)	✓	Client identifier in the provider's information system
result	number(3)	✓	Result code
comment	varchar2(254)		Result code description
timeout	number		Delay for the subsequent request (minutes)
extra			Extra information data
field1, field2, fieldN	varchar2(254)		Extra information
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

Payment Authorization

Upon receiving the request, the provider must perform internal checks on the possibility of making a payment with specified sysid and sysno parameters.

Request parameters

Request for payment authorization

<?xml version="1.0" encoding="UTF-8"?>
<request command="check">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
      <prov_code>044525521</prov_code>
    </id>
    <docattr>
      <mesid>4444</mesid>
      <docno/>
      <amount>100</amount>
      <comission/>
      <remarks/>
      <cbc/>
      <tax_no/>
      <tax_type/>
      <doc_type>3</doc_type>
    </docattr>
    <remitent>
      <rem_name/>
      <rem_nam2/>
      <rem_nam3/>
      <rem_tax/>
      <rem_kpp/>
      <rem_okato/>
      <rem_phone/>
      <rem_pob/>
      <rem_dob/>
      <rem_dcm_type/>
      <rem_dcm_serial_no/>
      <rem_dcm_no/>
      <rem_dcm_date/>
      <rem_dcm_issue_where/>
      <rem_address></rem_address>
      <rem_mfo>044585416</rem_mfo>
      <rem_acc></rem_acc>
      <rem_deb></rem_deb>
      <rem_cardno></rem_cardno>
      <rem_cardexp></rem_cardexp>
      <rem_key></rem_key>
      <rem_agrno></rem_agrno>
      <rem_extrainfo></rem_extrainfo>
    </remitent>
    <recipient>
      <rec_name></rec_name>
      <rec_nam2></rec_nam2>
      <rec_nam3></rec_nam3>
      <rec_tax></rec_tax>
      <rec_kpp></rec_kpp>
      <rec_okato></rec_okato>
      <rec_phone></rec_phone>
      <rec_pob></rec_pob>
      <rec_dob></rec_dob>
      <rec_dcm_type></rec_dcm_type>
      <rec_dcm_serial_no></rec_dcm_serial_no>
      <rec_dcm_no></rec_dcm_no>
      <rec_dcm_date></rec_dcm_date>
      <rec_dcm_issue_where></rec_dcm_issue_where>
      <rec_address></rec_address>
      <rec_mfo>044525521</rec_mfo>
      <rec_acc></rec_acc>
      <rec_cre>40817810700470049428</rec_cre>
      <rec_cardno></rec_cardno>
      <rec_cardexp/>
      <rec_key/>
      <rec_agrno/>
      <rec_extrainfo></rec_extrainfo>
    </recipient>
    <point>
      <terpfp></terpfp>
      <terid>9476886</terid>
      <terkvi/>
      <tercity>http://qiwi.ru</tercity>
      <teraddr></teraddr>
      <teragnt></teragnt>
    </point>
  </doc>
  <crypt>
    <cryp_prov/>
    <sign/>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>

Parameter	Format	Required	Description
command	`check`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
auth		✓	Authorization information
login	varchar2(30)	✓	Login
psw	varchar2(30)	✓	Password
doc		✓	Document information
id		✓	Document identifying informatin
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
prov_code	varchar2(9)	✓	Provider code
docattr		✓	Document attributes data
mesid	varchar2(5)	✓	Payment type
docno	varchar2(20)		Document number
amount	number	✓	Payment amount, in kopecks
comission	number		Payment commission, in kopecks
remarks	varchar2(160)		Note
cbc	varchar2(20)		Budget classifier code
tax_no	varchar2(20)		Tax document number
doc_type	varchar2(4)		Document type: `1` — account replenishment, `2` — credit repayment, `3`— card replenishment
tax_type	varchar2(2)		Tax document type
remittent			Payer data
rem_name	varchar2(254)		Payer last name or title
rem_nam2	varchar2(254)		Payer first name
rem_nam3	varchar2(254)		Payer surname
rem_tax	varchar2(12)		Payer TIN
rem_kpp	varchar2(26)		Payer registration reason code
rem_okato	varchar2(26)		Payer ОКАТО
rem_phone	number		Payer phone number
rem_pob	varchar2(254)		Payer birth place
rem_dob	date(`yyyymmdd`)		Payer date of birth
rem_dcm_type	varchar2(30)		Payer document type
rem_dcm_serial_no	varchar2(40)		Payer document serial number
rem_dcm_no	varchar2(40)		Payer document number
rem_dcm_date	date (`yyyymmdd`)		Payer document date of issue
rem_dcm_issue_where	varchar2(254)		Payer document issuer
rem_address	varchar2(254)		Payer address
rem_mfo	varchar2(9)	✓	Payer bank BIC
rem_acc	varchar2(25)		Payer bank corresponding account
rem_deb	varchar2(25)		Payer account in the bank
rem_cardno	varchar2(20)		Payer card number and card mask
rem_cardexp	varchar2(4)		Payer card expiration date
rem_key	varchar2(30)		Payer identifier in the bank
rem_agrno	varchar2(50)		Payer agreement identifier
rem_extrainfo	varchar2(512)		Payer additional information
recipient			Receiver data
reс_name	varchar2(254)	✓	Receiver last name or title
reс_nam2	varchar2(254)		Receiver name
reс_nam3	varchar2(254)		Receiver surname
reс_tax	varchar2(12)		Receiver TIN
reс_kpp	varchar2(26)		Receiver registration reason code
reс_okato	varchar2(26)		Receiver ОКАТО
reс_phone	number		Receiver phone number
reс_pob	varchar2(254)		Receiver place of birth
reс_dob	date (`yyyymmdd`)		Receiver date of birth
reс_dcm_type	varchar2(30)		Receiver document type
reс_dcm_serial_no	varchar2(40)		Receiver serial number of the document
reс_dcm_no	varchar2(40)		Receiver document number
reс_dcm_date	date (`yyyymmdd`)		Receiver document date of issue
reс_dcm_issue_where	varchar2(254)		Receiver document issuer
reс_address	varchar2(254)		Receiver address
reс_mfo	varchar2(9)	✓	Receiver bank BIC
reс_acc	varchar2(25)		Receiver bank corresponding account
reс_cre	varchar2(25)		Receiver account in the bank
reс_cardno	varchar2(20)		Receiver card number and card mask
reс_cardexp	varchar2(4)		Receiver card expiration date
reс_key	varchar2(30)		Receiver identifier in the bank
reс_agrno	varchar2(50)		Receiver agreement identifier
reс_extrainfo	varchar2(512)		Receiver additional information
point			Payment terminal data
terpfp	varchar2(50)		PFP number
terid	varchar2(20)	✓	Terminal identifier
terkvi	number		Receipt number
tercity	varchar2(150)		Termminal location city
teraddr	varchar2(254)		Terminal location address
teragnt	varchar2(254)		Terminal owner name
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

Response parameters

Response

<?xml version="1.0" encoding="UTF-8"?>
<response command="check">
  <verno>342</verno>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <prv_id>11137584</prv_id>
    <doctime>20211031124845</doctime>
    <amount>100</amount>
    <comission></comission>
    <rec_name></rec_name>
    <rec_name2></rec_name2>
    <rec_name3></rec_name3>
    <rec_cardno></rec_cardno>
    <rec_cre></rec_cre>
    <rec_agrno></rec_agrno>
    <rec_key></rec_key>
    <result>0</result>
    <comment>OK</comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

The provider must respond with XML document having root <response> tag and the following tags:

Parameter	Format	Required	Description
command	`check`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
amount	number	✓	Payment amount, in kopecks
comission	number		Payment commission, in kopecks
reс_name	varchar2(254)	✓	Receiver last name or title
reс_nam2	varchar2(254)		Receiver name
reс_nam3	varchar2(254)		Receiver surname
reс_cre	varchar2(25)		Receiver account in the bank
reс_cardno	varchar2(20)		Receiver card number and card mask
reс_key	varchar2(30)		Receiver identifier in the bank
reс_agrno	varchar2(50)		Receiver agreement identifier
result	number(3)	✓	Result code
comment	varchar2(254)	✓	Result code description
timeout	number		Delay for the subsequent request (minutes). The provider can recommend to repeat the request after that time, when non-fatal not `0` result code is obtained
extra			Extra information data
field1, field2, fieldN	varchar2(254)		Extra information for the provider
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

If the provider response contains <result>0</result>, it means that the payment with specified sysid and sysno parameters, and the specified amount can be registered.

The QIWI system turns to payment registration request after successful response.

Payment registration

Upon receiving the request, the provider must register the payment with specified sysid and sysno parameters.

Request parameters

Request

<?xml version="1.0" encoding="UTF-8"?>
<request command="pay">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
      <prov_code>044525521</prov_code>
    </id>
    <docattr>
      <mesid>4444</mesid>
      <docno></docno>
      <amount>100</amount>
      <comission></comission >
      <remarks></remarks>
      <cbc></cbc>
      <tax_no></tax_no>
      <tax_type></tax_type>
      <doc_type>3<doc_type>
    </docattr>
    <remitent>
      <rem_name></rem_name>
      <rem_nam2></rem_nam2>
      <rem_nam3></rem_nam3>
      <rem_tax></rem_tax>
      <rem_kpp></rem_kpp>
      <rem_okato></rem_okato>
      <rem_phone></rem_phone>
      <rem_pob></rem_pob>
      <rem_dob></rem_dob>
      <rem_dcm_type></rem_dcm_type>
      <rem_dcm_serial_no></rem_dcm_serial_no>
      <rem_dcm_no></rem_dcm_no>
      <rem_dcm_date></rem_dcm_date>
      <rem_dcm_issue_where></rem_dcm_issue_where>
      <rem_address></rem_address>
      <rem_mfo>044585416</rem_mfo>
      <rem_acc></rem_acc>
      <rem_deb></rem_deb>
      <rem_cardno></rem_cardno>
      <rem_cardexp></rem_cardexp>
      <rem_key></rem_key>
      <rem_agrno></rem_agrno>
      <rem_extrainfo></rem_extrainfo>
    </remitent>
    <recipient>
      <rec_name></rec_name>
      <rec_nam2></rec_nam2>
      <rec_nam3></rec_nam3>
      <rec_tax></rec_tax>
      <rec_kpp></rec_kpp>
      <rec_okato></rec_okato>
      <rec_phone></rec_phone>
      <rec_pob></rec_pob>
      <rec_dob></rec_dob>
      <rec_dcm_type></rec_dcm_type>
      <rec_dcm_serial_no></rec_dcm_serial_no>
      <rec_dcm_no></rec_dcm_no>
      <rec_dcm_date></rec_dcm_date>
      <rec_dcm_issue_where></rec_dcm_issue_where>
      <rec_address></rec_address>
      <rec_mfo>044525521</rec_mfo>
      <rec_acc></rec_acc>
      <rec_cre>40817810700470049428</rec_cre>
      <rec_cardno></rec_cardno>
      <rec_cardexp></rec_cardexp>
      <rec_key></rec_key>
      <rec_agrno></rec_agrno>
      <rec_extrainfo></rec_extrainfo>
    </recipient>
    <point>
      <terpfp></terpfp>
      <terid>9476886</terid>
      <terkvi></terkvi>
      <tercity>http://qiwi.ru</tercity>
      <teraddr></teraddr>
      <teragnt></teragnt>
    </point>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>

Parameter	Format	Required	Description
command	`pay`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
auth		✓	Authorization information
login	varchar2(30)	✓	Login
psw	varchar2(30)	✓	Password
doc		✓	Document information
id		✓	Document identifying informatin
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
prov_code	varchar2(9)	✓	Provider code
docattr		✓	Document attributes data
mesid	varchar2(5)	✓	Payment type
docno	varchar2(20)		Document number
amount	number	✓	Payment amount, in kopecks
comission	number		Payment commission, in kopecks
remarks	varchar2(160)		Note
cbc	varchar2(20)		Budget classifier code
tax_no	varchar2(20)		Tax document number
doc_type	varchar2(4)		Document type: `1` — account replenishment, `2` — credit repayment, `3`— card replenishment
tax_type	varchar2(2)		Tax document type
remittent			Payer data
rem_name	varchar2(254)		Payer last name or title
rem_nam2	varchar2(254)		Payer first name
rem_nam3	varchar2(254)		Payer surname
rem_tax	varchar2(12)		Payer TIN
rem_kpp	varchar2(26)		Payer registration reason code
rem_okato	varchar2(26)		Payer ОКАТО
rem_phone	number		Payer phone number
rem_pob	varchar2(254)		Payer birth place
rem_dob	date(`yyyymmdd`)		Payer date of birth
rem_dcm_type	varchar2(30)		Payer document type
rem_dcm_serial_no	varchar2(40)		Payer document serial number
rem_dcm_no	varchar2(40)		Payer document number
rem_dcm_date	date (`yyyymmdd`)		Payer document date of issue
rem_dcm_issue_where	varchar2(254)		Payer document issuer
rem_address	varchar2(254)		Payer address
rem_mfo	varchar2(9)	✓	Payer bank BIC
rem_acc	varchar2(25)		Payer bank corresponding account
rem_deb	varchar2(25)		Payer account in the bank
rem_cardno	varchar2(20)		Payer card number and card mask
rem_cardexp	varchar2(4)		Payer card expiration date
rem_key	varchar2(30)		Payer identifier in the bank
rem_agrno	varchar2(50)		Payer agreement identifier
rem_extrainfo	varchar2(512)		Payer additional information
recipient			Receiver data
reс_name	varchar2(254)	✓	Receiver last name or title
reс_nam2	varchar2(254)		Receiver name
reс_nam3	varchar2(254)		Receiver surname
reс_tax	varchar2(12)		Receiver TIN
reс_kpp	varchar2(26)		Receiver registration reason code
reс_okato	varchar2(26)		Receiver ОКАТО
reс_phone	number		Receiver phone number
reс_pob	varchar2(254)		Receiver place of birth
reс_dob	date (`yyyymmdd`)		Receiver date of birth
reс_dcm_type	varchar2(30)		Receiver document type
reс_dcm_serial_no	varchar2(40)		Receiver serial number of the document
reс_dcm_no	varchar2(40)		Receiver document number
reс_dcm_date	date (`yyyymmdd`)		Receiver document date of issue
reс_dcm_issue_where	varchar2(254)		Receiver document issuer
reс_address	varchar2(254)		Receiver address
reс_mfo	varchar2(9)	✓	Receiver bank BIC
reс_acc	varchar2(25)		Receiver bank corresponding account
reс_cre	varchar2(25)		Receiver account in the bank
reс_cardno	varchar2(20)		Receiver card number and card mask
reс_cardexp	varchar2(4)		Receiver card expiration date
reс_key	varchar2(30)		Receiver identifier in the bank
reс_agrno	varchar2(50)		Receiver agreement identifier
reс_extrainfo	varchar2(512)		Receiver additional information
point			Payment terminal data
terpfp	varchar2(50)		PFP number
terid	varchar2(20)	✓	Terminal identifier
terkvi	number		Receipt number
tercity	varchar2(150)		Termminal location city
teraddr	varchar2(254)		Terminal location address
teragnt	varchar2(254)		Terminal owner name
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

Response parameters

Response

<?xml version="1.0" encoding="UTF-8"?>
<response command="pay">
  <verno>342</verno>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <prv_id>11132331</prv_id>
    <doctime>20211031124845</doctime>
    <amount></amount>
    <comission></comission>
    <rec_name></rec_name>
    <rec_name2></rec_name2>
    <rec_name3></rec_name3>
    <rec_cardno></rec_cardno>
    <rec_cre></rec_cre>
    <rec_agrno></rec_agrno>
    <rec_key></rec_key>
    <result>0</result>
    <comment>OK</comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

The provider must respond with XML document having <response> tag and the following tags:

Parameter	Format	Required	Description
command	`pay`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
prv_id	varchar2(20)	✓	Transaction number in provider's system. Unique client account replenishment operation number, must be integer
amount	number	✓	Payment amount, in kopecks
comission	number		Payment commission, in kopecks
reс_name	varchar2(254)	✓	Receiver last name or title
reс_nam2	varchar2(254)		Receiver name
reс_nam3	varchar2(254)		Receiver surname
reс_cre	varchar2(25)		Receiver account in the bank
reс_cardno	varchar2(20)		Receiver card number and card mask
reс_key	varchar2(30)		Receiver identifier in the bank
reс_agrno	varchar2(50)		Receiver agreement identifier
result	number(3)	✓	Result code
comment	varchar2(254)	✓	Result code description
timeout	number		Delay for the subsequent request (minutes). The provider can recommend to repeat the request after that time, when non-fatal not `0` result code is obtained
extra			Extra information data
field1, field2, fieldN	varchar2(254)		Extra information for the provider
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

If the provider response contains <result>0</result>, it means that the payment with specified sysid and sysno parameters is successfully registered. In this case, the QIWI system finishes the processing of the transaction.

Cancellation of previously submitted payment

Upon receiving the request, the provider must cancel registration of the payment with specified sysid and sysno parameters.

Request parameters

Request

<?xml version="1.0" encoding="UTF-8"?>
<request command="cancel">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <sysid>22454</sysid>
    <sysno>09343439921</sysno>
    <doctime>20211031124845</doctime>
    <prov_code>044525521</prov_code>
    <prv_id>113242434</prv_id>
    <reason></reason>
    <amount>95</amount>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>

Parameter	Format	Required	Description
command	`cancel`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
auth		✓	Authorization information
login	varchar2(30)	✓	Login
psw	varchar2(30)	✓	Password
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
prov_code	varchar2(9)	✓	Provider code
prv_id	varchar2(20)	✓	Replenishment operation number in provider's system
reason	varchar2(160)	✓	Reasons for cancellation
docno	varchar2(20)	✓	Document number
amount	number	✓	Payment amount, in kopecks
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

Response parameters

Response

<?xml version="1.0" encoding="UTF-8"?>
<response command="cancel">
  <verno>342</verno>
  <doc>
    <sysid>22454</sysid>
    <sysno>09343439921</sysno>
    <doctime>20211031124845</doctime>
    <prv_id>113242434</prv_id>
    <docno></docno>
    <amount>95</amount>
    <result></result>
    <comment></comment>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

The provider must respond with XML document having <response> tag and the following tags:

Parameter	Format	Required	Description
command	`cancel`	✓	Request type identifier
verno	varchar2(30)	✓	Protocol version
doc		✓	Document information
sysid	varchar2(12)	✓	Payment system code
sysno	varchar2(24)	✓	Transaction number in the payment system
docno	varchar2(20)		Document number
doctime	date (`yyyymmddhh(24)mmss`)	✓	Transaction registration date and time in the payment system
prv_id	varchar2(20)	✓	Transaction number in provider's system
amount	number	✓	Payment amount, in kopecks
result	number(3)	✓	Result code
comment	varchar2(254)	✓	Result code description
timeout	number		Delay for the subsequent request (minutes). The provider can recommend to repeat the request after that time, when non-fatal not `0` result code is obtained
extra			Extra information data
field1, field2, fieldN	varchar2(254)		Extra information for the provider
crypt			Digital cignature data
cryp_prov	varchar2(20)		Cryptoprovider
sign	varchar2(50)		Payment signature
keyid	varchar2(20)		Key
encrypt	number(1)		"encrypted" (`1`) / "unencrypted" (`0`) flag

If the provider response contains <result>0</result>, it means that the payment with specified sysid and sysno parameters is successfully cancelled. In this case, the QIWI system cancels the payment.

Result codes

Code	Comment	Fatality
0	ОК	No
100	Incorrect Sender digital signature	Yes
101	Sender key expired	Yes
102	Sender key not registered	Yes
103	Sender key is blocked	Yes
104	Incorrect Payer digital signature	Yes
105	Payer key is blocked	Yes
106	Wrong login and password for server connection	Yes
109	Terrorist suspect	Yes
110	Unprocessable message	Yes
111	Incorrect document type	Yes
112	Incorrect payment type	Yes
119	Replenishment of foreign currency accounts and cards is forbidden	Yes
120	Incorrect Payer BIC	Yes
121	Incorrect Payer BIC or account	Yes
122	Incorrect Payer card number or expiry date	Yes
123	Incorrect Payer TIN	Yes
124	Incorrect Payer identifier	Yes
125	Payer account is blocked	Yes
126	Payer card is blocked	Yes
127	Wrong Payer card expiry date	Yes
128	Payer card expired	Yes
129	Incorrect Payer agreement number	Yes
130	No Payer name, date of birth, or place of birth in the request	Yes
131	Terminal number is absent or incorrect	Yes
132	No terminal address	Yes
133	Terminal agent number is absent or incorrect	Yes
134	No terminal agent name	Yes
135	No payment system code	Yes
136	No payment internal number	Yes
137	Incorrect birth date	Yes
138	Incorrect `doctime` format	Yes
139	`oper_type` field is not specified	Yes
140	Incorrect Receiver BIC	Yes
141	Incorrect Receiver account or BIC	Yes
142	Incorrect Receiver card number	Yes
143	Incorrect Receiver TIN	Yes
144	Incorrect Receiver identifier	Yes
145	Receiver account is blocked	Yes
146	Receiver card is blocked	Yes
147	Wrong Receiver card expiry date	Yes
148	Receiver card expired	Yes
149	Incorrect Receiver agreement number	Yes
150	Incorrect Receiver name	Yes
151	Amount too small	Yes
152	Amount too large or day limit for payments exceeded	Yes
153	Incorrect `amount` field format	Yes
154	Incorrect `comission` field format	Yes
155	Commission is bigger than the payment amount	Yes
156	Day limit for payments to the one account/card/agreement number exceeded	Yes
157	Payment amount is zero	Yes
159	Recevier of the payment cannot be identified	Yes
160	Rejected by Sender bank operator	Yes
161	Rejected by Receiver bank operator	Yes
162	Phone number not specified	Yes
171	`check` request not found or finished with error	Yes
172	Wrong payment type	Yes
181	Payment cannot be cancelled	Yes
189	Payment accepted for processing. Awaiting confirmation	Yes
190	Payment accepted for processing	Yes
191	Payment cannot be cancelled	Yes
192	Gift certificate expired	Yes
201	Archived	Yes
299	Creditor bank block	Yes
300	Operation cannot proceed by technical reasons. To make payment, contact your bank	Yes
301	Other system error	Yes

Payments register

Payment registers are transmitted by e-mail using one of the following encryption tools:

CryptoPro GOST 34.10-2001 CSP
CryptoARM Digital signature
Certification Authority CRYPTO-PRO LLC

The provider should follow the scheme for registry exchange:

sequenceDiagram participant bank as Recipient bank participant qb as QIWI Bank qb->>bank:Payments registry bank->>qb:Response registry qb-->>bank:Funds transfer on confirmed payments

Implementation Guidelines

The following ways for Digital signature implementation are preferrable:

Without digital signature
QIWI Bank RSA CA
GOST Crypto-Pro

Communication channel can be implemented by the following ways:

VPN (IPSec). Both HTTP and HTTPS is supported over VPN channel.
Without VPN:
- HTTPS one-way server authentication with RSA key
- HTTPS dual-way authentication with client certificate and RSA key
- HTTPS by GOST

Testing Guidelines

Testing the interaction of systems is mandatory. You need to provide test data:

If the identifier is an account, then an open and closed account details are required.
If the identifier is a card, then the numbers of the open card, the closed card, the blocked card are required.
For other identifiers, it is also necessary to provide the largest list of identifiers with different states in order to test the response of the service.

Usually, the following set of tests is performed:

With the correct identifier:
1. Sending check request, the amount of 50 rubles.
2. Sending check request, the amount is 0 rubles.
3. Sending check request, the amount is -1 ruble.
4. Sending check then pay requests, the amount is arbitrary.
5. Sending two pairs of check and pay requests with the same sysid and sysno values and an arbitrary amount to check that the payment will not be made twice.
6. Sending check + pay requests with the correct identifier and an arbitrary amount. After that, check + pay is sent with the same sysid and sysno values as the first pair of requests, but with an incorrect identifier, to check that the provider's system returns the completion status of the first deposit. Of course, in reality, this situation cannot arise when two replenishment requests are received with the same sysid and sysno, but different identifiers.
With an incorrect identifier:
1. Sending check request, the amount of 50 rubles.
2. Sending check + pay requests and an arbitrary amount.

If several identifiers are checked to complete a transaction, for example, account number and full name, then the number of tests increases due to the combination of options. For example, tests are performed with the correct account number and incorrect name.

Frequently Asked Questions

Question: If we receive a check request with the sysno and sysid values that have already come in the check request, should we give an error or give the result of a previous check request?

Answer: The result of the previous check request is expected.

Question: If we received a pay request for which there was no check request with the same sysno and sysid values, should we throw an error?

Answer: Yes, it is necessary to return the error 171 (Check was not found or passed with an error).

Question: If we receive a pay request, should we check the identity of all parameters of this request and the previously received check request with the same sysno and sysid values?

Answer: No, you should not. Optionally, you can check the amount.

Question: The sysid field is the code of the payment system. What payment system is meant, and what is this code?

Answer: The sysid parameter is the ID of the processing inside QIWI from which the payment was made. On the provider side, sysid is used to check the uniqueness of the sysid + sysno pair.

Question: In which fields will user identifiers be passed?

Answer: The contract number is rec_agrno, the account number is rec_cre, the card number is rec_cardno.

Question: What is the meaning of the mesid parameter?

Answer: With the standard implementation, the value will always be 3005 — the financial transaction for the check and pay requests. When reconciling non-standard logic (for example, returning the client's full name or debt to the interface), other values may be used.

Question: Can you process the value rec_name from our response to the check request, in which we will transfer the name of the owner of the specified card/account, for verification on your side and then transfer this value in the corresponding field of the pay request?

Answer: Yes, we can. In this case, the following sequence will be used:

We send you a check request with the <mesid>4444</mesid> parameter.
In the response, you confirm the possibility of replenishment and return your full name.
Full name is displayed in the interface.
The client makes the payment.
You get check and pay requests with <mesid>3005</mesid>.

Question: What fields are required in the provider's response messages to check and pay requests?

Answer: The following fields are required:

sysid
sysno
doctime – date of saving the transaction in the QIWI system
result
comment - if an error occurs, it is desirable to accurately indicate the cause of the error
prv_id