General Information

Edit on GitHub

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 QIWI Wallet users - pay.
2. Check the current status of the top-up payment - status.
3. Check the payment possibility - check-deposit-possible.
4. Check the user registration in QIWI Wallet service - check-user.
5. 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 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 and 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.

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 scenario of the QIWI Wallet top-up should go as follows:

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

SSL Authorization

Edit on GitHub

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

• Client certificate authorization
• Digital signature authorization

Using digital signature

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

You may use OpenSSL:

• Generate private key:

openssl genrsa -out private.key 2048

• Obtain public key:

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:

• Request for a certificate (OpenSSL example):

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.

• Make a corresponding public key (OpenSSL example):

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

• Give obtained public key and the request for a certificate to QIWI representative.
• CA server certificate and client certificate to use in requests are returned in response.

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

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>

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:

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:

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>

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:

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:

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>

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:

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:

User Availability Check

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

Request parameters

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

Response format

Successful request processing

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

Response data:

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:

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>

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:

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:

Payment Statuses

Edit on GitHub

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

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

Payment Processing Result Codes

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

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

XML Data Format