QIWI
Feedback
bss@qiwi.com
NAV Navbar
http PHP cURL

Pull Payments

Edit on GitHub

QIWI Pull Payments API opens a way to operations with QIWI Wallet invoices from your service. The following operations are supported:

Payment methods

To use API, complete registration and approvement of the agreement.

Integration methods

You can use the following integration methods with QIWI Wallet Pull Payments API:

Pull REST API

Edit on GitHub

Invoicing Operation Flow

Pull API Invoicing

Developer Tools

Authorization

Pull REST API requests are authorized through HTTP Basic-authorization with API ID and API password. Header is Authorization string and its value is Basic Base64(API_ID:API_PASSWORD).

user@server:~$ curl "server_URL"
  --header "Authorization: Basic MjMyNDQxMjM6NDUzRmRnZDQ0Mw=="
Parameter Description Type Required
API_ID Provider API identifier for authorization Integer +
API_PASSWORD API password for authorization String +
Shop ID Numeric identifier of the provider's service Integer +

Issuing Invoice

Creates new invoice to the specified phone number (wallet ID in QIWI Wallet).

Request → PUT

<?php
//Example
//Shop identifier from Merchant details page
$SHOP_ID = "21379721";
//API ID from Merchant details page
$REST_ID = "62573819";
//API password from Merchant details page
$PWD = "**********";
//Invoice ID
$BILL_ID = "99111-ABCD-1-2-1";
$PHONE = "79191234567";

$data = array(
    "user" => "tel:+" . $PHONE,
    "amount" => "1000.00",
    "ccy" => "RUB",
    "comment" => "Good purchase",
    "lifetime" => "2015-01-30T15:35:00",
    "pay_source" => "qw",
    "prv_name" => "Special packages"
);

$ch = curl_init('https://api.qiwi.com/api/v2/prv/'.$SHOP_ID.'/bills/'.$BILL_ID);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $REST_ID.":".$PWD);
curl_setopt($ch, CURLOPT_HTTPHEADER,array (
    "Accept: application/json"
));
$results = curl_exec ($ch) or die(curl_error($ch));
echo $results;
echo curl_error($ch);
curl_close ($ch);
//Optional user redirect
$url = 'https://oplata.qiwi.com/order/external/main.action?shop='.$SHOP_ID.'&
transaction='.$BILL_ID.'&pay_source=card';
echo '<br><br><b><a href="'.$url.'">Redirect link to pay for invoice</a></b>';
?>

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1"
  -X PUT  --header "Accept: text/json" --header "Authorization: Basic ***"
  -d "user=tel%3A%2B79161234567&amount=10.00&ccy=RUB&comment=test&lifetime=2016-09-25T15:00:00"
Parameter Description Type Required
user The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix String(20) Y
amount The invoice amount. The number is rounded down with two decimal places Number(6.2) Y
ccy Invoice currency identifier (Alpha-3 ISO 4217 code). Depends on currencies allowed for the merchant. The following values are supported: RUB, EUR, USD, KZT String(3) Y
comment Comment to the invoice String(255) Y
lifetime Date and time up to which the invoice is available for payment, URL-encoded ISO 8601 (YYYY-MM-DDThh:mm:ss), Moscow timezone. If the invoice is not paid by this date it will become void and will be assigned a final status.
Important! Invoice will be automatically expired when 45 days is passed after the invoicing date		 dateTime Y
pay_source If the value is mobile the user’s MNO balance will be used as a funding source. If the value is qw, any other funding source is used available in QIWI Wallet system for the user. If parameter isn’t present, value qw is assumed String N
prv_name Merchant’s name String(100) N

The given PHP example implements creation of the invoice and redirection to the QIWI Checkout web page for payment. This example demonstrates using merchant's authorization parameters, i.e. shop ID, API ID and password for the API ID. Open the PHP tab on the right.

Response ←


HTTP/1.1 200 OK
Content-Type: text/json

{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "My comment"
     }
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json

{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}


HTTP/1.1 200 OK
Content-Type: text/xml

<response>
   <result_code>0</result_code>
   <bill>
    <bill_id>BILL-1</bill_id>
    <amount>10.00</amount>
    <originAmount>10.00</originAmount>
    <ccy>RUB</ccy>
    <originCcy>RUB</originCcy>
    <status>rejected<status>
    <error>0</error>
    <user>tel:+79161234567</user>
    <comment>test</comment>
   </bill>
</response>

HTTP/1.1 401 Unauthorized
Content-Type: text/xml

<response>
   <result_code>341</result_code>
   <description>Authorization is failed</description>
</response>

Response format depends on Accept header in the request:

Parameter Type Description
result_code Integer Error code
description String Error description. Returned when result_code is non-zero.
bill Object Bill data. Returned when result_code is zero (successful operation). Parameters:
bill.bill_id String Unique invoice identifier generated by the merchant
bill.amount String The invoice amount. The number is rounded down with two decimal places.
bill.ccy String Currency identifier of the invoice (Alpha-3 ISO 4217 code)
bill.status String Current invoice status
bill.error Integer Always 0, means successful operation
bill.user String The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix.
bill.comment String Comment to the invoice

Checking Invoice Status

Gets payment status of the invoice.

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/sdf23452435"
  --header "Authorization: Basic ***" --header "Accept: text/json"

Request → GET

Response ←


HTTP/1.1 200 OK
Content-Type: text/json

{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "originAmount": "10.00",
        "ccy": "RUB",
        "originCcy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "My comment"
     }
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json

{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}


HTTP/1.1 200 OK
Content-Type: text/xml

<response>
   <result_code>0</result_code>
   <bill>
    <bill_id>BILL-1</bill_id>
    <amount>10.00</amount>
    <originAmount>10.00</originAmount>
    <ccy>RUB</ccy>
    <originCcy>RUB</originCcy>
    <status>rejected<status>
    <error>0</error>
    <user>tel:+79161234567</user>
    <comment>test</comment>
   </bill>
</response>

HTTP/1.1 401 Unauthorized
Content-Type: text/xml

<response>
   <result_code>341</result_code>
   <description>Authorization is failed</description>
</response>

Response format depends on Accept header in the request:

Parameter Type Description
result_code Integer Error code
description String Error description. Returned when result_code is non-zero.
bill Object Bill data. Returned when result_code is zero (successful operation). Parameters:
bill.bill_id String Unique invoice identifier generated by the merchant
bill.amount String The invoice amount. The number is rounded down with two decimal places.
bill.originAmount String The amount taken from the balance when the invoice get paid (see originCcy parameter). The number is rounded down with two decimal places. Returns for invoices when the user initiates payment.
bill.ccy String Currency identifier of the invoice (Alpha-3 ISO 4217 code)
bill.originCcy String Currency identifier of the balance from which the invoice is paid (Alpha-3 ISO 4217 code). Returns for invoices when the user initiates payment.
bill.status String Current invoice status
bill.error Integer Always 0, means successful operation
bill.user String The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix.
bill.comment String Comment to the invoice

Cancelling Unpaid Invoice

Cancels unpaid invoice provided that its lifetime has not expired yet.

user@server:~$ curl -X PATCH
  --header "Authorization: Basic ***"  --header "Accept: text/json"
  "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1"
  -d "status=rejected"

Request → PATCH

Response ←


HTTP/1.1 200 OK
Content-Type: text/json

{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "ccy": "RUB",
        "status": "rejected",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "My comment"
     }
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json

{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}


HTTP/1.1 200 OK
Content-Type: text/xml

<response>
   <result_code>0</result_code>
   <bill>
    <bill_id>BILL-1</bill_id>
    <amount>10.00</amount>
    <ccy>RUB</ccy>
    <status>rejected<status>
    <error>0</error>
    <user>tel:+79161234567</user>
    <comment>test</comment>
   </bill>
</response>

HTTP/1.1 401 Unauthorized
Content-Type: text/xml

<response>
   <result_code>341</result_code>
   <description>Authorization is failed</description>
</response>

Response format depends on Accept header in the request:

Parameter Type Description
result_code Integer Error code
description String Error description. Returned when result_code is non-zero.
bill Object Bill data. Returned when result_code is zero (successful operation). Parameters:
bill.bill_id String Unique invoice identifier generated by the merchant
bill.amount String The invoice amount. The number is rounded down with two decimal places.
bill.ccy String Currency identifier of the invoice (Alpha-3 ISO 4217 code)
bill.status String Rejected invoice status
bill.error Integer Always 0, means successful operation
bill.user String The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix.
bill.comment String Comment to the invoice

Refunds

Method processes a full or partial refund to user's QIWI Wallet account, so a reversed transaction with the same currency is created for the initial one.

Merchant can create several refund operations for the same initial invoice provided that:

Refund Operation Flow

Refund Invoice REST API

Request → PUT

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1/refund/REF1"
  -v -w "%{http_code}"
  -X PUT  --header "Accept: text/json"
  --header "Authorization: Basic ***"
  --header "Content-type: application/x-www-form-urlencoded; charset=utf-8"
  -d "amount=5.0"

Response ←


HTTP/1.1 200 OK
Content-Type: text/json

{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "REF1",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json

{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}


HTTP/1.1 200 OK
Content-Type: text/xml

<response>
  <result_code>0</result_code>
  <refund>
   <refund_id>REF1</refund_id>
   <amount>5.0</amount>
   <status>success<status>
   <error>0</error>
  </refund>
</response>

HTTP/1.1 401 Unauthorized
Content-Type: text/xml

<response>
   <result_code>341</result_code>
   <description>Authorization is failed</description>
</response>
Parameter Type Description
result_code Integer Error code
description String Error description. Returned when result_code is non-zero.
refund Object Refund data. Returned when result_code is zero (successful operation). Parameters:
refund.refund_id String The refund identifier, unique number in a series of refunds processed for a particular invoice
refund.amount String The actual amount of the refund. The positive number that is rounded down with two decimal places.
refund.status String Current refund status
refund.error Integer Error code.
Important! When the amount of refund exceeds the initial invoice amount or the amount left after the previous refunds, error code 242 is returned.

Check Refund Status

Method returns current status of the refund.

Request → GET

user@server:~$ curl "https://api.qiwi.com/api/v2/prv/373712/bills/BILL-1/refund/REF1"
  -v -w "%{http_code}"
  --header "Accept: text/json" --header "Authorization: Basic ***"

Response ←


HTTP/1.1 200 OK
Content-Type: text/json

{
   "response": {
      "result_code": 0,
      "refund": {
         "refund_id": "REF1",
         "amount": "5.00",
         "status": "success",
         "error": 0
      }
   }
}

HTTP/1.1 401 Unauthorized
Content-Type: text/json

{
 "response": {
  "result_code": 150,
  "description": "Authorization failed"
  }
}


HTTP/1.1 200 OK
Content-Type: text/xml

<response>
  <result_code>0</result_code>
  <refund>
   <refund_id>REF1</refund_id>
   <amount>5.0</amount>
   <status>success<status>
   <error>0</error>
  </refund>
</response>


HTTP/1.1 401 Unauthorized
Content-Type: text/xml

<response>
   <result_code>341</result_code>
   <description>Authorization is failed</description>
</response>
Parameter Type Description
result_code Integer Error code
description String Error description. Returned when result_code is non-zero.
refund Object Refund data. Returned when result_code is zero (successful operation). Parameters:
refund.refund_id String The refund identifier, unique number in a series of refunds processed for a particular invoice
refund.amount String The actual amount of the refund. The positive number that is rounded down with two decimal places.
refund.status String Current refund status
refund.error Integer Error code. Important! When the amount of refund exceeds the initial invoice amount or the amount left after the previous refunds, error code 242 is returned.

Operation Statuses

Invoice Status

Status Description Final
waiting Invoice issued, pending payment N
paid Invoice has been paid Y
rejected Invoice has been rejected Y
unpaid Payment processing error. Invoice has not been paid Y
expired Invoice expired. Invoice has not been paid Y

Refund Status

Status Description Final
processing Payment refund is pending N
success Payment refund is successful Y
fail Payment refund is unsuccessful Y

Error Codes

Code Description Fatal
0 Success Unrelated
5 Incorrect data in the request parameters Y
13 Server is busy, try again later N
78 Operation is forbidden Y
150 Authorization error (e.g. invalid login/password) Y
152 Protocol is not enabled or protocol is disabled N
155 This merchant’s identifier (API ID) is blocked Y
210 Invoice not found Y
215 Invoice with this bill_id already exists Y
241 Invoice amount is less than allowed Y
242 Invoice amount is greater than allowed. Also returns to refund request when the amount of refund exceeds the initial invoice amount or the amount left after the previous refunds Y
298 User not registered Y
300 Technical error N
303 Wrong phone number Y
316 Authorization from the blocked merchant N
319 No rights for the operation N
339 IP-addresses blocked Y
341 Required parameter is incorrectly specified or absent in the request Y
700 Monthly limit on operations is exceeded Y
774 QIWI Wallet user account temporarily blocked Y
934 Region is not supported  
1001 Currency is not allowed for the merchant Y
1003 No convert rate for these currencies N
1018 Country is not supported  
1019 Unable to determine wireless operator for MNO balance payment Y
1419 Bill was already payed Y

Online Invoicing Web Form

Edit on GitHub

Client receives a web form with selection of appropriate payment methods for the invoice.

Web form calling is performed without merchant's authorization. Client can input a phone number and an amount for invoicing on the web form directly.

Operations flow

Request → REDIRECT

GET /order/external/create.action?txn_id=10000&from=11223&summ=1.11&currency=643 HTTP/1.1
Host: bill.qiwi.com
Parameter Description Type Required
from Merchant identifier (Shop ID). Identifier is specified in "HTTP-protocol" part of "Settings" section of merchant's account on kassa.qiwi.com. Integer +
currency Invoice currency identifier (in Alpha-3 ISO 4217 code). Any currency may be used if specified in agreement with QIWI Wallet. String(3) +
to QIWI Wallet client phone number to make the invoice. If not specified, client should enter the phone on the web invoice form. String(20) -
summ Amount of the invoice. Positive number rounded to two fractional digits. Point as a separator. If not specified, client should enter the amount on the web invoice form. Number(6.2) -
txn_id Unique invoice number in online merchant store. It is used to identify specific invoice of the merchant. String(30), Latin letters and digits (without space) -
comm Merchant commentary to the invoice. If not specified and to parameter is absent, client may enter the comment with phone number at once on the web form. String(255) -
lifetime Invoice expiry date (YYYY-MM-DDTHHMM format). When time is expired, invoice cannot be paid and it would be cancelled. Important! Invoice will be automatically expired when 28 days is passed after the invoicing date. -  
pay_source Default payment method to show first for the client on QIWI Checkout. Possible values:
qw – QIWI Wallet account;
mobile – client’s cell phone account;
card – a credit/debit card;
wm – WebMoney wallet if linked to QIWI Wallet account;
ssk – payment by cash in a QIWI Terminal.
When specified method is inaccessible, the page contains notice about it and the client can choose another method.		 String (predefined) -

Checkout

Edit on GitHub

Merchant may offer the user to pay the invoice immediately by redirecting to the QIWI Wallet Checkout page via the HTTP GET-request.

GET /form?shop=2042&transaction=1234567&pay_source=qw HTTP/1.1
Host: oplata.qiwi.com

Request → REDIRECT

Parameter Type Description Required
shop string Merchant's ID in QIWI Wallet system, corresponds to prv_id parameter used to create the bill. Y
transaction string Invoice ID generated by the merchant, corresponds to bill_id parameter used to create the bill. Y
embedded boolean The checkout page appears more compact and can be embedded conveniently within the merchant’s site. Default value is false N
pay_source string Default payment method to show first on the page for the user. Allowed values:
qw – QIWI Wallet account;
mobile – client’s cell phone account;
card – a credit/debit card;
wm – linked WebMoney wallet;
ssk – payment by cash in a QIWI Terminal.
When specified method is inaccessible for the user, the page shows a notice about it and the client can choose another method.		 N

Redirection to Merchant Site

Redirect when transaction is successfully created

GET /success?a=1&b=2&order=1234567 HTTP/1.1
Host: example.com

Redirect when creation of transaction is unsuccessful

GET /fail?a=1&b=2&order=1234567 HTTP/1.1
Host: example.com

The URL for redirection supplements order parameter with its value as the original merchant's invoice ID. Using this parameter, the merchant can render the final page depending on the order details.

Notifications

Edit on GitHub

Notification is a POST-request (callback). The request's body contains all relevant data of the invoice serialized as HTTP-request parameters and encoded by UTF-8 plus parameter command=bill.

Request → POST

Example of notification request

user@server:~$ curl "https://example.com/qiwi-notify.php"
  -v -w "%{http_code}"
  -X POST --header "Accept: text/xml"
  --header "Content-Type: application/x-www-form-urlencoded; charset=utf-8"
  --Authorization: "Basic MjA0Mjp0ZXN0Cg=="
  -d "bill_id=BILL-1%26status=paid%26amount=1.00%26user=tel%3A%2B79031811737%26prv_name=TEST%26ccy=RUB%26comment=test%26command=bill"
Parameter Description Type Required
bill_id Merchant invoice number String Y
status Current invoice status String Y
amount The invoice amount. The number is rounded down with two decimal places Number(6.2) Y
user The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with tel: prefix String Y
prv_name Merchant’s site name specified on kassa.qiwi.com in "Settings" section String Y
ccy Invoice currency identifier (Alpha-3 ISO 4217 code) String(3) Y
comment Comment to the invoice String(255) Y
command Always bill by default String Y

Response ←

Example of XML response to notification

HTTP/1.1 200 OK
Content-Type: text/xml

<?xml version="1.0"?>
<result>
<result_code>0</result_code>
</result>

Response must be in XML format.

XML Tag Description
result Grouping tag. Describes notification processing result.
result_code Notification result code (positive integer). We recommend that the result codes returned by the merchant be in accordance with Notification codes table.

Authorization on Merchant's Server

Merchant's server should use basic-authorization or authorization by signature. Merchant may also use client SSL certificate verification (self-signed certificates may be used as well). QIWI Wallet server certificate should be verified in HTTPS requests.

Basic authorization

Example of notification with Basic auth

POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
Authorization: Basic ***
Host: example.com

command=bill&bill_id=BILL-1&status=paid&error=0&amount=1.00&user=tel%3A%2B79031811737&prv_name=Retail_Store&ccy=RUB&comment=test

The login is taken from Shop ID parameter. To obtain password, click on Change notification password button in Protocols details - REST-protocol section of QIWI partners web site.

Authorization by signature

Example of notification with Signature

POST /qiwi-notify.php HTTP/1.1
Accept: text/xml
Content-type: application/x-www-form-urlencoded
X-Api-Signature: J4WNfNZd***V5mv2w=
Host: example.com

command=bill&bill_id=LocalTest17&status=paid&error=0&amount=0.01&user=tel%3A%2B78000005122&prv_name=Test&ccy=RUB&comment=Some+Descriptor

Example of notification processing with signature check

<?php

function hexToStr($hex){
    $string='';
    for ($i=0; $i < strlen($hex)-1; $i+=2){
        $string .= chr(hexdec($hex[$i].$hex[$i+1]));
    }
    return $string;
}

//Signature generation by key and string
function checkSign($key, $req){
    $sign_hash = hash_hmac("sha1", $req, $key);
    $sign_tr = hexToStr($sign_hash);
    $sign = base64_encode($sign_tr);
    return $sign;
}

//Sort POST-request parameters and return values
function getReqParams(){
    $reqparams = "";
    ksort($_POST);
    foreach ($_POST as $param => $valuep) {
        $reqparams = "$reqparams|$valuep";
    }
    return substr($reqparams,1);
}

//Take signature from the request
function getSign(){
    $HEADERS = getallheaders();
    foreach ($HEADERS as $header => $value) {
       if ($header == 'X-Api-Signature') {
            $SIGN_REQ = $value;
       }
    }
    return $SIGN_REQ;
}

// Sort parameters
$Request = getReqParams();
// Notification password
$NOTIFY_PWD = "***";
// Get sign
$reqres = checkSign($NOTIFY_PWD, $Request);

// Get sign from the request
$SIGN_REQ = getSign();

if ($reqres == $SIGN_REQ) {
    $error = 0;
}
else $error = 151;

//Response
header('Content-Type: text/xml');
$xmlres = <<<XML
<?xml version="1.0"?>
<result>
<result_code>$error</result_code>
</result>
XML;
echo $xmlres;
?>

The HTTP header X-Api-Signature with signature is added to the POST-request. Signature is calculated as HMAC algorithm with SHA1-hash function.

Signature verification algorithm is as follows:

  1. Prepare a string of all parameters values from the notification POST-request sorted in alphabetical order and separated by |:

    {parameter1}|{parameter2}|…

    where {parameter1} is the value of the notification parameter. All values should be treated as strings.

  2. Transform obtained string and password for the notification basic-authorization into bytes encoded in UTF-8.

  3. Apply HMAC-SHA1 function:

    hash = HMAС(SHA1, Notification_password_bytes, Invoice_parameters_bytes) Where:

    • Notification_password_bytes – secret key (bytecoded notification password);
    • Invoice_parameters_bytes – bytecoded POST-request body;
    • hash – hash-function result.
  4. Transform HMAC-hash value into bytes with UTF-8 and Base64-encode it.
  5. Compare X-Api-Signature header's value with the result of step 4.

PHP Implementation Example

The given PHP example implements notification authorization by signature verification. Open the PHP tab on the right.

Notification Codes

Code Description
0 Success
5 The format of the request parameters is incorrect
13 Database connection error
150 Incorrect password
151 Signature authorization failed
300 Server connection error
http PHP cURL