Feedback
bss@qiwi.com
NAV Navbar
Examples

Introduction

Last update: 2019-11-15

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 you

  1. Send money to customer's payment card - pay(0).
  2. Send money to customer's QIWI Wallet - pay(1).
  3. Monitor the agent's balance - ping.

How it works

Payment Card Top Up

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

QIWI Wallet Top Up

  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.

Feedback

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 uses Agent ID and password to authenticate requests to the API (in terminal-id and extra name="password" XML tag, respectively). To change password, contact QIWI Wallet staff. The Agent may also use client certificate and digital signature methods to authenticate requests.

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's credentials (Agent ID and password) are provided accordingly.

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 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: 2019-11-11 | 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 must provide the public key to QIWI representative and use the private key in a request signing:

POST /xml/topup.jsp HTTP/1.1
Content-Type: application/xml
Host: api.qiwi.com
X-Digital-Sign: XXXXXXXX
X-Digital-Sign-Alg: SHA1withRSA

  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 HTTP headers 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 use client certificate in API requests, 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

Payment Card Top Up Request

Last update: 2019-11-15

Payment card top-ups are payment transactions within QIWI Wallet system that debit Agent accounts and credit customer's payment card account in international payment systems VISA, MasterCard and MIR. Payment system is determined by the card number.

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 (contact QIWI Wallet Support by bss@qiwi.com).

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

Request parameters

<?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>1115.00</amount>
				<ccy>RUB</ccy>
				<service-id>34020</service-id>
				<account-number>4265111122334411</account-number>
			</to>
		</payment>
	</auth>
</request>
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 customer's payment card account.
service-id Service identifier (constant: 34020)
account-number VISA / MasterCard / MIR payment card number without spaces to top up. Only cards issued by Russian Federation credit institutions.
ccy Currency of the top up transaction (RUB accepted only)

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>34020</service-id>
    	<amount>15.00</amount>
    	<ccy>643</ccy>
    	<account-number>4111********1123</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 customer's payment card No
service-id Service identifier No
account-number Masked card 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

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 account and credit user QIWI Wallet account.

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

Request parameters

<?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>
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

Transaction 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 the status request, the Agent’s system should repeat the 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

Request parameters

<?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>
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

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 parameters

<request>
<request-type>ping</request-type>
<terminal-id>44</terminal-id>
<extra name="password">password</extra>
</request>
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

Successful request processing

<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)

Error response

If QIWI Wallet server is unable to process the 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

Payment Statuses

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 34020)
215 Top-up request has payment transaction number (transaction-number) that is already registered in QIWI Wallet but other parameters of the transaction differ. Transaction parameters must be in agreement with this payment transaction number.
220 Not enough funds available on the Agent’s account to process payment
242 Payment amount is greater than allowed
300 Unknown processing error. Contact QIWI Wallet technical support: bss@qiwi.com
316 Authorization from the blocked agent

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 (34020 for payment card top up, 99 for QIWI Wallet top up)
from/service-id Integer positive
account-number For QIWI Wallet top up transactions - International phone number (without leading + sign);
For payment cards top up transactions - card number, only 0-9 digits without spaces
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)