Pull REST API {#pull_rest_api}

Edit on GitHub

Invoicing Operation Flow

User submits an order on the merchant’s website.
Merchant service issues invoice.
To increase successful payments conversion, merchant is recommended to redirect the user to QIWI Checkout page on QIWI Wallet site, to pay for the invoice. Otherwise, invoice can be paid in any QIWI Wallet interfaces, such as web (qiwi.com), mobile applications and self-service terminals.
If the merchant enables notifications, then its service receives a notification from QIWI Wallet system once invoice is paid or cancelled by the user. Authorization on the merchant's side is required for notifications.
In any case, merchant can request current status of the invoice, or cancel invoice (provided that the user has not initiated payment yet).
When the invoice payment is confirmed, merchant delivers ordered services/goods.

Invoicing operation on Pull REST API is idempotent, so on two consecutive requests with the same prv_id, bill_id and amount parameters the same response code is returned.

Developer Tools {#node_sdk}

NODE JS SDK - Node JS package of ready-to-use solutions for server2server integration development to begin accepting payments on your site.

Authorization {#auth_param}

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=="

Authorization and form data
Data can be obtained on kassa.qiwi.com

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	+

To obtain service data, open "Protocols - REST - Authorization" section on kassa.qiwi.com.

Details

Issuing Invoice {#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.'&successUrl=http%3A%2F%2Fexample.com%2Findex.php%3Froute%3D
payment%2Fqiwi%2Fsuccess&failUrl=http%3A%2F%2Fexample.com%2Findex.php%3Froute%3D
payment%2Fqiwi%2Ffail&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"

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in "Shop ID" parameter of "Protocols Settings" section of kassa.qiwi.com web site)
- bill_id - unique invoice identifier generated by the merchant (any non-empty string of up to 200 characters). Uniqueness means that the identifier must not coincide with any of previously issued invoices of the merchant.

HEADERS
- Accept: text/json or Accept: application/json - JSON response
- Accept: text/xml or Accept: application/xml - XML response
- Content-type: application/x-www-form-urlencoded; charset=utf-8
- Authorization: Basic ***

Parameters
Parameters are sent in the request body as formdata.

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:

HEADERS
- Accept: text/json or Accept: application/json - response in JSON
- Accept: text/xml or Accept: application/xml - response in XML

Parameters

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 {#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

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in "Shop ID" parameter of "Protocols Settings" section of kassa.qiwi.com web site)
- bill_id - invoice identifier

HEADERS
- Accept: text/json or Accept: application/json - JSON response
- Accept: text/xml or Accept: application/xml - XML response
- Authorization: Basic ***

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:

HEADERS
- Accept: text/json or Accept: application/json - response in JSON
- Accept: text/xml or Accept: application/xml - response in XML

Parameters

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 {#cancel}

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

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in "Shop ID" parameter of "Protocols Settings" section of kassa.qiwi.com web site)
- bill_id - invoice identifier
- status - rejected (cancelling status).

HEADERS
- Accept: text/json or Accept: application/json - JSON response
- Accept: text/xml or Accept: application/xml - XML response
- Content-type: application/x-www-form-urlencoded; charset=utf-8
- Authorization: Basic ***

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:

HEADERS
- Accept: text/json or Accept: application/json - response in JSON
- Accept: text/xml or Accept: application/xml - response in XML

Parameters

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 {#refund}

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:

Amount of all refund operations does not exceed initial invoice amount.
Different refund IDs used for different refund operations of the same invoice (see below).

When the transmitted amount exceeds the initial invoice amount or the amount left after the previous refunds, server returns error code 242.

Refund Operation Flow

Merchant sends a request for refund to QIWI Wallet server.
To make sure that the payment refund has been successfully processed, merchant can periodically request the invoice refund status until the final status is received.
This scenario can be repeated multiple times until the invoice is completely refunded (whole invoice amount has been returned to the user).

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"

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in "Shop ID" parameter of "Protocols Settings" section of kassa.qiwi.com web site)
- bill_id - identifier of the invoice to be refunded
- refund_id - the refund identifier, a number specific to a series of refunds for the invoice {bill_id} (string of 1 to 9 symbols – any 0-9 digits and upper/lower Latin letters)
- amount - the refund amount. It should be less or equal to the amount of the original invoice specified in bill_id. The positive number that is rounded down with two decimal places.

HEADERS
- Accept: text/json or Accept: application/json - JSON response
- Accept: text/xml or Accept: application/xml - XML response
- Content-type: application/x-www-form-urlencoded; charset=utf-8
- 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>

HEADERS
- Accept: text/json or Accept: application/json - response in JSON
- Accept: text/xml or Accept: application/xml - response in XML

Parameters

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 ***"

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in Shop ID parameter of Protocols details section of kassa.qiwi.com web site)
- bill_id - invoice identifier
- refund_id - refund identifier, a number specific to a series of refunds for the invoice {bill_id} (string of 1 to 9 symbols – any 0-9 digits and upper/lower Latin letters)

HEADERS
- Accept: text/json or Accept: application/json - JSON response
- Accept: text/xml or Accept: application/xml - XML response
- 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>

HEADERS
- Accept: text/json or Accept: application/json - response in JSON
- Accept: text/xml or Accept: application/xml - response in XML

Parameters

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 {#status}

Invoice Status {#status_bills}

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_refund}

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

Error Codes {#errors}

Fatal means the result will not change with the second and subsequent requests (error is not temporary)

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

Files

_pull-payments-api_en.html.md

Latest commit

History

_pull-payments-api_en.html.md

File metadata and controls

Pull REST API {#pull_rest_api}

Edit on GitHub

Invoicing Operation Flow

Developer Tools {#node_sdk}

Authorization {#auth_param}

Authorization and form data

Details

Issuing Invoice {#invoice}

Request → PUT

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Parameters

Response ←

HEADERS

Parameters

Checking Invoice Status {#invoice-status}

Request → GET

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Response ←

HEADERS

Parameters

Cancelling Unpaid Invoice {#cancel}

Request → PATCH

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id

HEADERS

Response ←

HEADERS

Parameters

Refunds {#refund}

Refund Operation Flow

Request → PUT

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id

HEADERS

Response ←

HEADERS

Parameters

Check Refund Status

Request → GET

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id/refund/refund_id

HEADERS

Response ←

HEADERS

Parameters

Operation Statuses {#status}

Invoice Status {#status_bills}

Refund Status {#status_refund}

Error Codes {#errors}