QIWI
Feedback
bss@qiwi.com
NAV Navbar

Interface to QIWI Wallet Payments for Service Providers

The interaction between QIWI Wallet service and the provider is built in the "request-response" mode, where the initiator of the request is always the QIWI Wallet service, and the response always comes from the provider.

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

When processing requests from the QIWI Wallet service, the provider must perform the required operation and then respond with the data (if required) and the operation result code.

To connect with the interface, a provider should:

  1. Implement the requirements for the interface
  2. Comply with rules for processing requests
  3. Implement payment process.

Provider's Interface Requirements

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

  1. 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.
  2. Respond to QIWI Wallet request using XML format in UTF-8 encoding.
  3. Response time should not exceed 60 seconds, otherwise QIWI Wallet service would disconnect by timeout.
  4. 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, or more).
  5. 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.

  6. 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.

  7. Interface should accept requests only from QIWI subnet IP-addresses:

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 and return corresponding code in <result> XML tag.

There are fatal and non-fatal error codes:

For example, not having a connection to the provider's server is a non-fatal error. The absence of the <result> tag in the answer or incorrect XML or Service temporarily unavailable page are also non-fatal errors.

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

Payment Processing

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

The provider needs to implement processing requests on each of these steps. At the same time, the provider must comply with the request processing rules.

Get extra parameters of payment

On receiving the request, the provider check the presence of a subscriber in its database with the specified ID and return extra parameters for showing them to the customer. These extra parameters can then be transferred as additional payment details in check and pay requests.

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=getInfo&prvId=12345&account=4957835959&name1=%26%30AB&name2=0
Parameter Format Description
command getInfo Required. Identification of the type of request: get additional payment data for the customer. Always equal to getInfo.
account String of letters, digits, and special symbols, up to 200 symbols Required. Subscriber's identifier in the provider's database (account number, phone number, login etc). Before sending the request, QIWI Wallet system verify the identifier to match to the provider's regular expression.
prvId Integer Required. Service identifier in th provider's information system.
parameter_name Specified in provider's application form Additional parameters for the subscriber identification

Response parameters

Response example

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <type hasList="true" hasInfo="true"/>
  <extra>
   <list>
    <field name="service1">account1</field>
   </list>
   <info>
    <field name="service2">term2</field>
   </info>
  </extra>
  <result>0</result>
  <comment>OK</comment>
</response>

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

Tag Description
type Required. Indication of presence or absence of <info> and <list> sections in the response. Attributes hasList and hasInfo are always there. These values mean the following. If hasList="true", then there is <list> section inside <extra> tag. Likewise, if hasInfo="true", then there is <info> section inside <extra> tag. See below.
extra Data list for the customer
list Required if attribute hasList="true". Fields list for the customer choice
fields name="field1" One tag corresponds to the field from the selector for customer's choice. The name of the field is in name attribute, the value of the field is the tag value. There may be several tags in the response, with different values of the attribute. Selected element may be transmitted back to the provider as extra[field1]=value parameter in check and pay requests (see below).
info Required if attribute hasInfo="true". Fields list to display any information to the customer
fields name="field1" One tag corresponds to the field for displaying to the customer. The name of the field is in name attribute, the displaying value is the tag value. There may be several tags in the response, with different values of the attribute.
result Required. Operation result code (<result>0</result> if request is successfully processed)
comment Comment for the operation

Check the status of the subscriber

On receiving the request, the provider 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 business 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: example.com:8443

command=check&txn_id=1234567&account=4950001111&sum=100.45&ccy=RUB

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=100.45&ccy=RUB&extra[name1]=data1
Parameter Format Description
command check Required. Identification of the type of request: check the subscriber's account. Always equal to check
txn_id Integer (up to 20 digits) Required. Payment identifier in QIWI Wallet service. The provider's database must not contain two successful payments with the same txn_id. 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.
account String of letters, digits, and special symbols, up to 200 symbols Required. Subscriber's identifier in the provider's database (account number, phone number, login etc). Before sending the request, QIWI Wallet system verify the identifier to match to the provider's regular expression.
sum Fractional number, rounded to two digits, decimal separator . If integer, zero decimals must be added Required. Payment amount to top up to the subscriber's account.
ccy Alpha-3 ISO 4217 Currency code Required. Currency of the payment's amount
extra[parameter_name] Digits, underscore (_) and Latin letters (a-z) Additional details for the payment (extra fields). There may be several parameters in the request. It is used when provider cannot process the payment without extra data (when only providing subscriber's account is not enough).
For example, customer identifier is a card number, but for payment processing you also need card expiration date.
A list of necessary fields to send to the provider should be specified before the system integration.

Response parameters

Response example

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <osmp_txn_id>1234567</osmp_txn_id>
  <prv_txn>2016AB</prv_txn>
  <sum>100.45</sum>
  <ccy>RUB</ccy>
  <result>0</result>
  <comment>OK</comment>
</response>

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

Tag Description
osmp_txn_id Required. QIWI Wallet transaction identifier (txn_id from the request)
prv_txn Required. Unique number of the customer's balance top-up operation in the provider's system
sum Required. Parameter sum from the request
ccy Required. Parameter ccy from the request
result Required. Operation result code (<result>0</result> when payment can be accepted)
comment Comment to the operation

Register the payment

On receiving the request, provider 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=20190815120133&account=4957835959&sum=100.45&ccy=RUB
Parameter Format Description
command pay Required. Request type: replenish the client's balance. Always pay
txn_id Integer (up to 20 digits) Required. Payment identifier in QIWI Wallet service. The provider's database must not contain two successful payments with the same txn_id. 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.
txn_date YYYYMMDDHHMMSS Required. Payment date. In QIWI Wallet service it is the date of receiving request from the customer. Reconciliation between QIWI Wallet service and the provider's system is performed by this date.
For example, the customer sends request to QIWI Wallet service at 23:59:59 on 31.12.2019. QIWI Wallet service sends the request to provider at 00:00:05 on 01.01.2020. This might result in discrepancy at reconciliation, if the provider's system puts the transaction in the next period of reconciliation. To avoid such problems, QIWI Wallet service gives the original payment date to the provider.
account String of letters, digits, and special symbols, up to 200 symbols Required. Subscriber's identifier in the provider's database (account number, phone number, login etc). Before sending the request, QIWI Wallet system verify the identifier to match to the provider's regular expression.
sum Fractional number, rounded to two digits, decimal separator . If integer, zero decimals must be added Required. Payment amount to top up to the subscriber's account.
ccy Alpha-3 ISO 4217 Currency code Required. Currency of the payment's amount
extra[parameter_name] Digits, underscore (_) and Latin letters (a-z) Additional details for the payment (extra fields). There may be several parameters in the request. It is used when provider cannot process the payment without extra data (when only providing subscriber's account is not enough).
For example, customer identifier is a card number, but for payment processing you also need card expiration date.
A list of necessary fields to send to the provider should be specified before the system integration.

Response parameters

Response example

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <osmp_txn_id>1234567</osmp_txn_id>
   <prv_txn>2016AB</prv_txn>
   <sum>100.45</sum>
   <ccy>RUB</ccy>
   <result>0</result>
   <comment>OK</comment>
   <fields>
       <field name="prv-date">2019-08-15T12:06:45</field>
   </fields>
</response>

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

Tag Description
osmp_txn_id Required. QIWI Wallet transaction identifier (txn_id from the request)
prv_txn Required. Unique number of the customer's balance top-up operation in the provider's system
sum Required. Parameter sum from the request
ccy Required. Parameter ccy from the request
result Required. Operation result code (<result>0</result> when payment can be accepted)
field name="prv-date" Required. Date/time of payment acceptance in the provider's system, in YYYY-MM-DDTHH:MM:SS format (example: 2019-02-03T00:00:07). This date is used for accounting settlements.
comment Comment for the operation

Daily Reconciliation

QIWI Wallet system generates and sends payments list processed during the day before to the certain address specified in provider's configuration in the QIWI Wallet 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 ; symbol, and 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:

27.02.2019 00:04:00;27.02.2019 00:00:00;Payment;3464968222;USD;5.00;;;;;0957835959;;

27.02.2019 00:04:00;27.02.2019 00:00:00;Payment;3464968912;RUB;10.34;;;;;test@example.org;;

27.02.2019 00:11:00;27.02.2019 00:00:00;Payment;3464974548;EUR;4.72;;;;;ABC-12345;;

QIWI Wallet 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 Wallet 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 Wallet side. Please specify those in the initial application for QIWI Wallet.

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

Requests authorization by client SSL certificate is also supported. Please enclose PKCS12 client certificate for QIWI Wallet in your initial application form for the integration.

Application Form for New Provider

  1. Provider’s organization legal name (as pointed in the agreement).

  2. Provider’s short name (to be displayed in user interface).

  3. Message to prompt user to input subscriber’s identifier (to be shown in user interface).

    (For example: “Please type your MSISDN”)

  4. The URL of the payment processing application.

    (For example: https://merchant.example.org:8443/payment_app.cgi)

  5. Login and password if Basic authorization needed.

  6. Email for daily transaction reports.

  7. Reward rate in % to be owed to QIWI Wallet for each payment.

  8. Regular expression for validation of subscriber’s identifier.

  9. Non-existing merchant’s account. (This account must match given regular expression for validation of subscriber’s identifier, but must not exists in merchant’s system; it will be used to test merchant’s implementation; debits to this account is not used during reconciliation)

  10. Test merchant’s accounts (two accounts minimum). (These accounts will be used to test merchant’s implementation; debits to this accounts are not used during reconciliation).

  11. Merchant’s server certificate in X.509 format (if used).

  12. Client certificate for QIWI authentication in PKCS12 format (if authorization with client certificate is needed).

  13. Provider’s support email.

  14. Extra payment parameters (sample).

    • Technical name of the parameter – must be a meaningful name of a parameter. For example, variants such as a1, abc are not allowed for "Username" field. Technical name must only contain digits, underscore and lowercase letters of the Latin alphabet ([0-9_a-z]).
    • Name displayed in UI – text to show as the field description in user interface.
    • Description – detailed parameters description.
    • Regular expression – used for input data validation.
    • Input mask – used on user interface to constraint data input:
      • w – represents an alphabetic character;
      • d – represents a numeric character.

Example of extra parameters:

Technical name of the parameter Name displayed in UI Description Regular expression Input mask
valid_thru Card expires after Month and year of card expiration. Month and year are included in card lifetime. \d{2}/\d{2} dd/dd

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