Feedback
bss@qiwi.com
NAV
XML

Introduction

Last update: 2017-11-15 | Edit on GitHub

Top-Up API is intended for merchants or payment service providers (PSP) who need to send money back to QIWI Wallet users.

What API allows

  1. Send money to QIWI Wallet users - pay.
  2. Check the user registration in QIWI Wallet service - check-user.
  3. Monitor the agent’s balance - ping.

How it works

  1. A user provides you a QIWI Wallet account and money amount to top-up.
  2. You send a request to QIWI Wallet Top-Up API to top-up the account.
  3. You check the payment’s current status till it becomes final.
  4. On successful status, money is transferred from your agent’s account to the user’s QIWI Wallet account.
  5. On unsuccessful status, money is returned to the user.

Please contact us on bss@qiwi.com for integration and cooperation.

API Structure

The Agent’s system uses HTTPS protocol to send POST requests to

https://api.qiwi.com/xml/topup.jsp

All requests and responses are XML documents encoded in UTF-8 in HTTP body. All tags and attributes of the requests in the document are necessary to be present in requests (if not specified otherwise for a certain tag/attribute). It is not an API contract violation that any other tags/attributes might be added in responses or requests.

See Values Format of XML tags and attributes.

Agent must make decision on successful or unsuccessful payment processing based on transaction status in QIWI Wallet system.

Agent must assign a unique identifier for each payment completely characterized by a set of parameters: amount, currency, QIWI Wallet user account, service identifier.

Agent will be notified if any update of the API is taken place.

See section Implementation Guidelines for the algorithm to be implemented at the Agent’s side.

Agent Account

To use the API, the Agent should set up an agent’s account with QIWI Wallet. The amounts credited to user accounts are taken from the Agent’s account balance.

The Agent uses Agent ID and password to authenticate requests to the API. To change password, contact QIWI Wallet staff. The Agent may also use client certificate and digital signature methods to authenticate requests.

QIWI Wallet User Accounts

QIWI Wallet identifies its users by mobile phone number.

To top up user account in QIWI Wallet, the Agent specifies user’s mobile phone number and the amount in a top-up request.

Implementation Guidelines

The interaction of the Agent’s system with QIWI Wallet should go as follows.

Top-up logic to be implemented by the Agent’s system

The Agent system should implement the logic shown in the flowchart below. Some details are omitted from the flowchart for readability, particularly retrying requests to QIWI Wallet in case of non-fatal error.

Interaction between Agent and QIWI Wallet

SSL Authorization

Last update: 2017-07-27 | Edit on GitHub

Besides identifier/password authorization, two other authorization types may be also used:

Using digital signature

To use digital signature, the Agent has to create a public/private key pair using RSA.

You may use OpenSSL:

openssl genrsa -out private.key 2048

openssl rsa -in private.key -pubout -out public.key

Thus, obtained key corresponds to the requirements.

The Agent has to give the public key to QIWI representative and use the private key in a request signing:

  1. Calculate hash on the text of an XML request using MD5 or SHA1 algorithm, sign it by saved private key and make a Base64-encode. A digital sign of the request is obtained as a result.
  2. Transfer the following parameters in HTTP header with the XML request to authorize and check its data integrity:
    • X-Digital-Sign – digital sign created on the previous point.
    • X-Digital-Sign-Alg – algorithm of the digital sign calculation. Specify one of the following values corresponding to the algorithm used on the previous point:
      • MD5withRSA - if MD5 used,
      • SHA1withRSA - if SHA1 used.

Using client certificate

To authorize requests by client certificate, you should send them to

https://private-api.qiwi.com/xml/topup.jsp

To use client certificate, the Agent has to give request for a certificate and public key to QIWI representative:

openssl req -new -nodes -batch -subj "/C=RU/ST=Russia/L=Moscow/O=QIWI/emailAddress=mail@qiwi.ru" -newkey rsa:2048 -keyout private_key.pem -out cert_request.csr

Specify your data in the request: language, country, city, name of your organization and e-mail address. In the example, QIWI data is used.

openssl rsa -in private_key.pem -pubout -out public.key

Sample request with certificate:

user@pc:~/private-api$ openssl s_client -connect private-api.qiwi.com/xml/topup.jsp:443 -showcerts -CAfile ./CA/our_CA -cert ./my_cert -key ./private_key.pem

QIWI Wallet Top-Up Request

Last update: 2017-11-14 | Edit on Github

QIWI Wallet top-ups are payment transactions within QIWI Wallet system that debit Agent accounts and credit user accounts.

If the specified user account does not exist, QIWI Wallet system creates it automatically while processing the top-up request.

All payment transactions, including top-up requests, are processed asynchronously. A request that is accepted successfully may then fail.

The Agent’s system should query payment status from QIWI Wallet periodically (no more than once in 10 minutes), until a final status code, successful or unsuccessful, is received.

The Agent’s system should process errors as follows.

In case of network error (connection or response timeout) or HTTP error (HTTP status code other than 200, or empty HTTP response), incorrect XML-documents (no required tag/attribute) the Agent’s system should request payment status until final successful or unsuccessful payment status. Transaction status information is inaccessible in case of these errors, so the Agent should not denies the payment on its side.

Fatal errors mean that sending a secondary request with the same parameters will result in the same error. Fatal errors are often caused by invalid configuration and require manual intervention.

In case of fatal error, the Agent’s system may either keep repeating requests, or pause repeating the request until the configuration is corrected. Agent’s system needs not to deny payment as transaction status is unknown on request processing error.

Request format

<?xml version="1.0" encoding="utf-8"?>
<request>
	<request-type>pay</request-type>
	<terminal-id>123</terminal-id>
	<extra name="password">***</extra>
	<auth>
		<payment>
			<transaction-number>12345678</transaction-number>
			<from>
				<ccy>RUB</ccy>
			</from>
			<to>
				<amount>15.00</amount>
				<ccy>RUB</ccy>
				<service-id>99</service-id>
				<account-number>79181234567</account-number>
			</to>
		</payment>
	</auth>
</request>

Request parameters

Tag Description
request A grouping tag. The child tags contain payment parameters
request-type Request type identifier (QIWI Wallet top-up request: pay)
terminal-id Agent ID in QIWI Wallet system
extra name=”password” Agent’s password in QIWI Wallet system
auth A grouping tag that describes payment data
payment A grouping tag that describes single payment details. There must be only one such tag in the request.
transaction-number transaction number generated by the Agent’s system. This number should be used in payment status check request. Transaction number and Agent ID make a uniquely identified transaction in QIWI Wallet system.
from A grouping tag that contains payment details related to Agent’s account
ccy Currency of the Agent’s balance that will be charged for the payment (numeric or character code of currency according to ISO 4217)
service-id Top-up source identifier (optional). The service-id parameter is used when it is necessary to separate QIWI Wallet top-up sources in the Agent’s balance.
to A grouping tag with the payment details
amount Amount to be credited to QIWI Wallet user account. QIWI Wallet system limits payment amount taking into account conditions on a money balance on QIWI Wallet user account specified in QIWI Wallet offer https://static.qiwi.com/ru/doc/oferta_lk.pdf. Amounts less than allowed and greater than allowed are not accepted. The operation will be finished with result code 241 and 242, respectively.
service-id Service identifier (constant: 99)
account-number QIWI Wallet user ID, i.e. the mobile phone number in international format
extra=”comment” Payment comment (optional)
ccy Currency of the user (recipient) account where payment is debited (numeric or character code of currency according to ISO 4217)

Response format

Successful request processing

<response>
<payment status='60' txn_id='6060' transaction-number='12345678' result-code='0' final-status='true' fatal-error='false' txn-date='02.03.2011 14:35:46'  >
  <from>
    <amount>15.00</amount>
    <ccy>643</ccy>
  </from>
  <to>
    <service-id>99</service-id>
    <amount>15.00</amount>
    <ccy>643</ccy>
    <account-number>79181234567</account-number>
  </to>
</payment>
<balances>
<balance code="428">0.00</balance>
<balance code="643">200</balance>
<balance code="840">12.20</balance>
</balances>
</response>

Response data:

Tag Description Attributes
response A grouping tag No
payment Details of the accepted payment statuspayment status in QIWI Wallet system;
    txn_id – transaction ID in QIWI Wallet system. If empty, the payment was not registered due to temporary error. You have to repeat the request later.;
    transaction-number – transaction number in the Agent’s system;
    result-code – payment processing error code;
    final-status – logical flag indicating if payment’s status is final;
    fatal-error - logical flag indicating if payment’s processing error is fatal;
    txn-date – date and time when the payment was accepted by QIWI Wallet system.
from A grouping tag with information about charged money from the Agent’s account No
amount The amount charged from the Agent’s account No
ccy Currency of the Agent’s account (numeric or character code of currency according to ISO 4217) No
to A grouping tag with payment details No
amount The amount credited to QIWI Wallet user account No
service-id Service identifier (constant: 99) No
account-number QIWI Wallet user ID, i.e. the mobile phone number No
ccy Currency of the payment (numeric or character code of currency according to ISO 4217) No
balances A grouping tag. Child tags corresponds to the Agent’s account balances in QIWI Wallet system after the payments was accepted No
balance Value of balance in currency of the Agent’s account code - shows the currency of the Agent’s balance (numeric code of currency according to ISO 4217)

Error response

If QIWI Wallet server is unable to process the top-up request, the response is as follows:

<response>
  <result-code fatal="false">300</result-code>
</response>

Response data:

Tag Description Attributes
result-code Request processing error code fatal – logical flag indicating if payment processing error is fatal

Payment Status Check

Last update: 2017-11-14 | Edit on GitHub

To check if a payment was completed successfully, the Agent’s system must query payment status from QIWI Wallet periodically, until a final status code, successful or unsuccessful, is received.

When registered in QIWI Wallet system, a payment passes through a set of states with different statuses. Each status is specified by its unique numeric identifier. Payment processing is treated as complete when it reaches a final status. Status codes are listed in Payment statuses.

The request allows obtaining current payment status. Repeating request for the same payment should be used no more than once in 10 minutes.

In case of non-fatal error or non-final payment status received in response to status request, the Agent’s system should repeat the payment status check request.

Fatal errors mean that sending a secondary request with the same parameters will result in the same error.

Fatal errors are often caused by invalid configuration and require manual intervention. In case of fatal error, the Agent’s system may either keep repeating requests, or pause repeating the request until the configuration is corrected. Agent’s system needs not to deny payment as transaction status is unknown on request processing error. Transaction status information is inaccessible in case of these errors, so the Agent should not denies the payment on its side.

In case of network error (connection or response timeout) or HTTP error (HTTP status code other than 200, or empty HTTP response), incorrect XML-documents (no required tag/attribute) the Agent’s system should repeat request. Transaction status information is inaccessible in case of these errors, so the Agent should not denies the payment on its side.

Request format

<?xml version="1.0" encoding="utf-8"?>
  <request>
    <request-type>pay</request-type>
    <extra name="password">XXXXXX</extra>
    <terminal-id>123</terminal-id>
    <status>
      <payment>
        <transaction-number>12345678</transaction-number>
        <to>
             <account-number>79181234567</account-number>
        </to>
      </payment>
    </status>
  </request>

Request parameters

Tag Description
request A grouping tag. The child tags contain payment data
request-type Request type (payment status check is the same as top-up request: pay)
terminal-id Agent ID in QIWI Wallet system
extra name=”password” Agent’s password in QIWI Wallet system
status A grouping tag. The tag contains child tags with payments data to check their status (one or more payment tag)
payment A grouping tag containing single payment data to check its status
transaction-number Transaction number generated by the Agent’s system and specified in top-up request. Together with Agent ID, transaction number uniquely identifies the payment in QIWI Wallet system. Transaction number always stays immutable within payment lifetime.
to A grouping tag with payment information
account-number QIWI Wallet user ID, i.e. the mobile phone number in international format

Response format

Successful request processing

<response>
  <result-code fatal="false">0</result-code>
  <payment status='60' transaction-number='12345678' txn_id='759640439' result-сode='0' final-status='true'  fatal-error='false' txn-date='12.03.2012 14:24:38'  />
  <balances>
    <balance code="643">90.79</balance>
    <balance code="840">0.00</balance>
  </balances>
</response>

Response data:

Tag Description Attributes
response A grouping tag No
payment Details of the checked payment. When several payments status check is requested, response contains corresponding payment tags. When payment in the request is not found in QIWI Wallet system, corresponding payment tag will be absent in the response. You have to repeat payment status check request for that payment. statuspayment status in QIWI Wallet system;
    txn_id – transaction ID in QIWI Wallet system;
    transaction-number – transaction number in the Agent’s system;
    result-code – payment processing error code;
    final-status – logical flag indicating if payment status is final;
    fatal-error - logical flag indicating if payment processing error is fatal;
    txn-date – date and time when the payment was accepted by QIWI Wallet system;
balances A grouping tag. The child tags are current balances of the Agent’s active accounts in QIWI Wallet system No
balance Balance of the Agent’s account code - currency of the Agent’s account (numeric code of currency according to ISO 4217)

Error response

If QIWI Wallet server is unable to process payment status request, the response is as follows.

<response>
  <result-code fatal="false">300</result-code>
</response>

Response data:

Tag Description Attributes
result-code Request processing error code fatal – logical flag indicating if request processing error is fatal

User Availability Check

Last update: 2017-11-15 | Edit on GitHub

QIWI Wallet Top-Up API provides Agent with ability to check if the user is registered in QIWI Wallet system. User availability is not a requirement for a payment registration. If the specified user account does not exist, it will be created upon top-up request.

Request format

<?xml version="1.0" encoding="utf-8"?>
<request>
  <request-type>check-user</request-type>
  <terminal-id>123</terminal-id>
  <extra name="password">XXXXX</extra>
  <extra name="phone">79031234567</extra>
  <extra name="ccy">RUB</extra>
</request>

Request parameters

Tag Description
request A grouping tag. The child tags contain payment parameters
request-type Request type (user availability check: check-user)
terminal-id Agent ID in QIWI Wallet system
extra name”password” Agent’s password in QIWI Wallet system
extra name=”phone” User’s phone number. This number is used to check whether user account with the specified number is already registered in QIWI Wallet system
extra name=”ccy” Currency of user account balance. Optional parameter (numeric or character code of currency according to ISO 4217), in this case QIWI Wallet system checks whether user has balance in this currency.

Response format

<response>
  <result-code fatal="false">0</result-code>
  <exist>1</exist>
</response>

Response data:

Tag Description Attributes
result-code The result code of the request processing fatal – logical flag indicating fatal (unchanged) error.
exist Flag indicating whether the user is registered in QIWI Wallet system. The flag is included only in case of successful request processing (error code 0). The flag may have one of the following values:
0 – the user is not registered in QIWI Wallet system (if extra name="ccy" tag is specified in the request, then the user does not have balance in the specified currency);
1 – the user is registered in QIWI Wallet system (if extra name="ccy" tag is specified in the request, then the user has balance in the specified currency).
No.

Balance Check Request

Last update: 2017-11-14 | Edit on GitHub

Agent can check the balance of the Agent’s account in QIWI Wallet system at any time using balance check request.

Request format

<request>
<request-type>ping</request-type>
<terminal-id>44</terminal-id>
<extra name="password">password</extra>
</request>

Request parameters

Parameter Description
request A grouping tag
request-type Request type (balance check: ping)
terminal-id Agent ID in QIWI Wallet system
extra name=”password” Agent’s password in QIWI Wallet system

Response format

<response>
<result-code fatal="false">0</result-code>
<balances>
  <balance code="428">100.00</balance>
  <balance code="643">200.26</balance>
  <balance code="840">300.00</balance>
</balances>
</response>

Response data:

Tag Description Attributes
response A grouping tag No
result-code The result code of the request processing fatal – logical flag indicating fatal (unchanged) error.
balances A grouping tag. The child tags are current balances of the Agent’s active accounts in QIWI Wallet system No
balance Balance of the Agent’s account code - currency of the Agent’s account (numeric code of currency according to ISO 4217)

Payment Statuses

Last update: 2017-11-14 | Edit on GitHub

QIWI Wallet server may return payment status from the following ranges:

Status Description Final?
-1 The payment is not registered due to temporary error. Please repeat the request later.  
0-49 The payment is accepted but waiting for the confirmation from QIWI Wallet system. Contact QIWI Wallet technical support: bss@qiwi.com -
50-59 The payment is being processed. The amount has been charged from the Agent’s account. -
50 The payment is accepted for processing -
52 The amount is being credited to the user account -
60 The payment has been processed successfully +
> 100 Processing error. The amount has been put back to the Agent’s balance +
150 The payment declined +
151 The payment authorization error +
160 The payment is not processed or has been canceled +

Error codes for unsuccessful final states are listed in payment processing results.

Payment Processing Result Codes

Error code Error description
0 No errors
155 Invalid service code (service-id in top-up request should be 99)
215 Top-up request has payment transaction number (transaction-number) that is already registered in QIWI Wallet but other parameters differ. Payment parameters have to be in agreement with this payment transaction number.
220 Not enough funds available on the Agent’s account to process payment
241 Payment amount is less than allowed
242 Payment amount is greater than allowed
298 User account with specified phone number is not registered in QIWI Wallet system. Invalid phone number as user account ID.
300 Unknown processing error. Contact QIWI Wallet technical support: bss@qiwi.com
316 Authorization from the blocked agent
319 Top-up of this user account is blocked
700 Monthly limit on operations is exceeded
702 QIWI Wallet client’s account balance limit is exceeded

If there are errors appeared that is not described in this table please contact QIWI Wallet technical support: bss@qiwi.com.

QIWI Wallet Error Codes

Error code Description Fatal?
0 No errors Inapplicable
13 Repeat the request in a minute -
150 Authorization error. Make sure that login and password are correct and repeat the request +
300 Unknown error. Repeat the request -
339 Sender IP address blocked +

If there are errors appeared that is not described in this table please contact QIWI Wallet technical support: bss@qiwi.com.

XML Data Format

Tag/attribute Data type
request-type Text with letters only
terminal-id Integer positive
transaction-number Integer positive up to 20 digits
amount Decimal (with two fractional digits separated by point)
to/service-id Constant (99)
from/service-id Integer positive
account-number International phone number (without leading + sign)
final-status Logical (true/false)
fatal-error Logical (true/false)
txn-date Timestamp formatted as:
dd.MM.yyyy HH:mm:ss
balance Decimal (with two fractional digits separated by point)
fatal Logical (true/false)
exist 0/1
"password" Text
"comment" Text (up to 1000 symbols)
"phone" International phone number (without leading + sign)
XML