QIWI
Feedback
bss@qiwi.com
NAV Navbar
Examples

General Information

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

What API allows you

  1. Send money to customer's payment card — pay(0) method.
  2. Send money to customer's QIWI Wallet — pay(1) method.
  3. Check the current status of the top-up payment — status method.
  4. Check the possibility of QIWI Wallet top-up payment — check-deposit-possible method.
  5. Monitor the agent's balance — ping method.

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 until 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 check payment possibility.
  3. You send a request to QIWI Wallet Top-Up API to top-up the account.
  4. You check the payment's current status until it becomes final.
  5. On successful status, money is transferred from your agent's account to the user's QIWI Wallet account.
  6. On unsuccessful status, money is returned to the user.

Feedback

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

API Structure

All requests and responses are XML documents encoded in UTF-8 in HTTP body.

See Values Format of XML tags and attributes.

Agent uses Agent ID and password to authenticate API requests. Place Agent ID in terminal-id and password in extra name="password" XML tags, respectively. To change password, contact QIWI Wallet staff.

To improve the security of information exchange, the Agent may also use client certificate or digital signature methods to authenticate requests.

The Agent’s system in production environment must use HTTPS protocol and send only POST requests to URL

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

When using client certificate for requests authentication, the Agent’s system in production environment must use HTTPS protocol and send only POST requests to URL

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

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

Scenario for payment card top-ups

The scenario should go as follows:

sequenceDiagram participant Agent participant qb as QIWI Wallet Service Agent->>qb:Request to top-up client's card ("pay/auth" request) qb->>Agent:Response (payment status or error) Agent->>Agent:Final status? alt If final status not received loop Cycle until receiving final status Agent->>qb:Check top-up payment status ("pay/status" request) qb->>Agent:Response with current payment status end end alt Success / Final qb->>qb:Funds top-up to client's card end alt Fail / Final Agent->>Agent:Return funds to client end

Scenario of the QIWI Wallet top-up

The scenario should go as follows:

sequenceDiagram participant Agent participant qb as QIWI Wallet Service Agent->>qb:Check payment possibility
("check-deposit-possible" request) qb->>Agent:Response alt Payment is possible Agent->>qb:Request to top-up client's account ("pay/auth" request) qb->>qb:Creating wallet
when no account is found qb->>Agent:Response (payment status or error) Agent->>Agent:Final status? alt If final status not received loop Cycle until receiving final status Agent->>qb:Check top-up payment status ("pay/status" request) qb->>Agent:Response with current payment status end end alt Success / Final qb->>qb:Funds top-up to client's wallet end alt Fail / Final Agent->>Agent:Return funds to Client end end

Top-up logic flowchart

The Agent's system should implement the logic shown in the flowchart below.

graph TB ST(BEGIN TOP-UP PROCESS) -.- A ST -.-> |skip action
in case of card top-up|K A[Check Payment Possibility Request] --> B{Payment
is possible?} B -->|yes| C{User ID exists??} B -->|no| G[[Payment NOT processed]] C -->|yes| K C -->|no| H{Create user
and register payment?} H -->|yes| K[QIWI Wallet Top-up Request
or Card Top-up Request] H -->|no, if no such user, then
do not process payment| G K -->KN{Network error?} KN & KER -->|yes| KW([Wait 10 minutes or more]) KER -->|no| PFS KN -->|no| KER{Request processing error?} PFS -->|final-status=true| RS{'status' attribute value?} PFS -->|final-status=false| MR KW --> MR[Payment Status Check Request] RS -->|> 100| G RS -->|=60| X[[Payment processed successfully]] MR --> MER{Network error?} MER -->|no| MW{Request processing error?} MW & MER -->|yes| KW MW -->|no| PT{Is there 'payment' tag
with the 'txn_id' transaction number
in response?} PT -->|yes| PFS{'final-status' attribute?} PT -->|no| KW subgraph !!Mandatory steps for QIWI Wallet Top-up!! B A C H end

SSL Authorization

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

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 issued by the banks of Russian Federation. Payment system is determined by the card number.

The top-up request initiates the payment lifecycle. During the lifecycle, the payment proceeds through several statuses. 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 current payment status from QIWI Wallet periodically (no more than once in 10 minutes), until a final status code, successful or unsuccessful, is received.

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
from/ccy Currency of the Agent's balance that will be charged for the payment (numeric or character code of currency according to ISO 4217)
from/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
to/amount Amount to be credited to customer's payment card account.
to/service-id Service identifier (constant: 34020)
to/account-number VISA / MasterCard / MIR payment card number without spaces to top up. Only cards issued by Russian Federation credit institutions.
to/ccy Currency of the top up transaction (RUB accepted only)

Response format

The Agent’s system should process errors in response 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.

Successful request processing

<?xml version="1.0" encoding="utf-8"?>
<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>1115.00</amount>
    	<ccy>643</ccy>
  	</from>
  	<to>
    	<service-id>34020</service-id>
    	<amount>955.00</amount>
    	<ccy>643</ccy>
    	<account-number>4111********1123</account-number>
  	</to>
	</payment>
	<balances>
		<balance code="428">0.00</balance>
		<balance code="643">200.00</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
from/amount The amount charged from the Agent's account No
from/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
to/amount The amount credited to customer's payment card No
to/service-id Service identifier No
to/account-number Masked card number No
to/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
balances/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 request, the response is as described here.

<?xml version="1.0" encoding="utf-8"?>
<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

QIWI Wallet Top-Up

Edit on Github

QIWI Wallet top-ups are payment transactions within QIWI Wallet system that debit Agent account and credit user QIWI Wallet account. You have to check if the top-up is possible before the request.

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

The Agent must specify the type of funds that is received from the client — cash or non-cash funds, in extra name="income_wire_transfer" parameter.

The top-up request initiates the payment lifecycle. During the lifecycle, the payment proceeds through several statuses. 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 current payment status from QIWI Wallet periodically (no more than once in 10 minutes), until a final status code, successful or unsuccessful, is received.

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>
  <extra name="income_wire_transfer">1</extra>
  <auth>
    <payment>
      <transaction-number>12345678</transaction-number>
      <from>
        <ccy>RUB</ccy>
      </from>
      <to>
        <amount>1115.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
extra name="income_wire_transfer" The type of funds that the Agent received from the client - cash (0) or non-cash (1)
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
from/ccy Currency of the Agent's balance that will be charged for the payment (numeric or character code of currency according to ISO 4217)
from/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
to/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.
to/service-id Service identifier (constant: 99)
to/account-number QIWI Wallet user ID, i.e. the mobile phone number in international format
to/ccy Currency of the user (recipient) account where payment is debited (numeric or character code of currency according to ISO 4217)
to/extra="comment" Payment comment (optional)

Response format

The Agent’s system should process errors in response 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.

Successful request processing

<?xml version="1.0" encoding="utf-8"?>
<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>1115.00</amount>
    <ccy>643</ccy>
  </from>
  <to>
    <service-id>99</service-id>
    <amount>1000.00</amount>
    <ccy>643</ccy>
    <account-number>79181234567</account-number>
  </to>
</payment>
<balances>
<balance code="428">0.00</balance>
<balance code="643">200.00</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
from/amount The amount charged from the Agent's account No
from/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
to/service-id Service identifier (constant: 99) No
to/account-number QIWI Wallet user ID, i.e. the mobile phone number No
to/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
balances/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 request, the response is as described here.

<?xml version="1.0" encoding="utf-8"?>
<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

Transaction Status Check

Edit on GitHub

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. All possible status codes are listed in Payment statuses.

To check if a payment is completed successfully, the Agent’s system should use this API method to query payment status in QIWI Wallet, until a final status code, successful or unsuccessful, is received.

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
to/account-number QIWI Wallet user ID, i.e. the mobile phone number in international format

Response format

In case of non-fatal error or non-final payment status received in response to the request, the Agent’s system should repeat the 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 the request. Transaction status information is inaccessible in case of these errors, so the Agent should not reject the payment on its side.

Successful request processing

<?xml version="1.0" encoding="utf-8"?>
<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
balances/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.

<?xml version="1.0" encoding="utf-8"?>
<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

Check Payment Possibility

Edit on GitHub

This API method checks whether a top-up payment can go ahead. The Agent should check if the payment can be processed by the API.

If you need to check the user registration only, use another request.

Request format

Request parameters

<?xml version="1.0" encoding="utf-8"?>
<request>
  <request-type>check-deposit-possible</request-type>
  <terminal-id>123</terminal-id>
  <extra name="password">XXXXX</extra>
  <extra name="phone">79031234567</extra>
  <extra name="income_wire_transfer">1</extra>
</request>
Tag Description
request A grouping tag. The child tags contain payment parameters
request-type Request type (user account check: check-deposit-possible)
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
extra name="income_wire_transfer" Integer flag to indicate the type of funds that the Agent received from the client for its wallet's replenishment - cash (0) or non-cash (1).
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 payment to top-up the user's account in this currency is possible.

Response format

Successful request processing

Example - payment processing is possible

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false">0</result-code>
  <exist>1</exist>
  <deposit-possible>1</deposit-possible>
</response>

Example - payment processing is impossible

<?xml version="1.0" encoding="utf-8"?>
<response>
    <result-code fatal="true" message="Недостаточный статус идентификации кошелька для проведения платежа" msg="Недостаточный статус идентификации кошелька для проведения платежа">204</result-code>
    <exist>1</exist>
    <deposit-possible>0</deposit-possible>
</response>

Response data:

Tag Description Attributes
result-code The result code of the request processing fatal – logical flag indicating fatal (unchanged) error.
exist Integer 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.
deposit-possible Integer flag indicating whether the user account in QIWI Wallet system can be replenished. 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 account cannot be replenished by specified type of funds. Payment will be rejected
1 – the user account can be replenished by specified type of funds.
No.

Error response

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

<?xml version="1.0" encoding="utf-8"?>
<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

Edit on GitHub

This API method helps Agent to check the balance of the Agent’s account in QIWI Wallet system.

Request format

Request parameters

<?xml version="1.0" encoding="utf-8"?>
<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

<?xml version="1.0" encoding="utf-8"?>
<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.

<?xml version="1.0" encoding="utf-8"?>
<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. If you received status other than -1 in previous top-up request, continue requesting payment status, until final status is received  
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 (tag to/service-id in top-up request should be 34020 for payment card top up, and 99 for QIWI Wallet top up)
204 Insufficient wallet identification status for wallet top-up payment
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
0 No errors
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
to/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
income_wire_transfer 0/1
"password" Text
"comment" Text (up to 1000 symbols)
"phone" International phone number (without leading + sign)
"deposit-possible" 0/1