title

search

metatitle

metadescription

language_tabs

services

toc_footers

includes

Mobile payments API Mobile commerce

true

Mobile payments API Mobile commerce

Mobile payments API Mobile commerce provides access to operations with customer's mobile account of a mobile network operator from your application. API supports initiating payment for invoice from mobile network operator, as well as requesting operation statuses.

shell

php

<a href='#'>Swagger</a> | <a href='#'>Qiwi Demo</a>

pull-payments/notification_en

Payments From Mobile Account

Edit on GitHub

Mobile payments API provides access to operations with customer's mobile account from your application or service. The following operations are supported:

Payment initiation
Checking invoice payment status
Payment notifications

Customer Order Payment Flow {#steps}

Payment flow processes as follows:

The customer puts an order on the merchant's site.
Merchant makes Initiate Payment request with the authorization parameters.
Customer receives SMS from their mobile network operator immediately on initiating payment. SMS contains the information about corresponding payment invoice.
Customer approves payment by the response SMS. The invoice is automatically rejected when customer rejects the payment.

{:height="45%" width="45%"}
If the merchant enables notifications to merchant's server, then QIWI system sends a notification (web-hook) of the invoice payment to the merchant's server once invoice is paid. Authorization on the merchant's side is required for notifications.

If merchant does not use notifications, they can request current payment status of the invoice.
When the invoice payment is confirmed, merchant delivers ordered services/goods.

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

Authorization {#auth_param}

Mobile payments 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).

curl "server_address" \
  --header "Authorization: Basic MjMyNDQxMjM6NDUzRmRnZDQ0Mw=="

Authorization and forms
You can obtain the data on kassa.qiwi.com site

Service data {#auth_param}

Parameter	Description	Type
API_ID	Required. Provider API identifier for authorization	Integer
API_PASSWORD	Required. API password for authorization	String
Shop ID	Required. Numeric identifier of the provider's service	Integer

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

Details

Payment Initiation {#invoice_rest}

The request initiates a new payment for a specified mobile phone number. Request type - HTTP PUT.

To confirm payment, customer's mobile network operator send SMS with code to the specified phone number.

Request → PUT

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%2B79161111111&amount=10.00&ccy=RUB&comment=test&pay_source=mobile&lifetime=2016-09-25T15:00:00'

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:+79161111111",
        "comment": "Text comment"
     }
  }
}

URL https://api.qiwi.com/api/v2/prv/prv_id/bills/bill_id
- prv_id - merchant’s Shop ID (numeric value, as displayed in "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
- Content-type: application/x-www-form-urlencoded; charset=utf-8
- Authorization: Basic ***

Parameters
Parameters are sent in the request body as url-encoded formdata.

Parameter	Description	Type
user	Required. The QIWI Wallet user’s ID, to whom the invoice is issued. It is the user’s phone number with `tel:` prefix	String(20)
<<<<<<< HEAD
amount	Required. The invoice amount. The number is rounded down with two decimal places	Number(6.2)
=======
amount	Required. The invoice amount. The number is rounded down with two decimal places	Number(6.2)

842a7af... Required column is moved to parameter description ccy | Invoice currency identifier (Alpha-3 ISO 4217 code). Depends on currencies allowed for the merchant in QIWI system | String(3) comment | Required. Comment to the invoice | String(255) lifetime | Required. 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 pay_source |Required. A funding source for the payment — the customer's MNO balance | mobile only

The given PHP example implements creation of the invoice. 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 ←

Successful response

HTTP/1.1 200 OK

Content-Type: text/json;charset=utf-8
{
  "response": {
     "result_code": 0,
     "bill": {
        "bill_id": "BILL-1",
        "amount": "10.00",
        "ccy": "RUB",
        "status": "waiting",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "Text comment"
     }
  }
}

Error Response

HTTP/1.1 500 Internal Server Error
Content-Type: text/json;charset=utf-8

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

Fields

Response field	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 to two decimals
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

<?php
//PHP implementation of invoice creation
//Shop identifier
$SHOP_ID = "21379721";
//API ID
$REST_ID = "62573819";
//API Password
$PWD = "**********";
//Invoice ID
$BILL_ID = "99111-ABCD-1-2-1";
$PHONE = "79191234567";

$data = array(
    "user" => "tel:+" . $PHONE,
    "amount" => "1000.00",
    "ccy" => "RUB",
    "comment" => "Goods from basket",
    "lifetime" => "2015-01-30T15:35:00",
    "pay_source" => "mobile"
);

$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);
?>

Checking Payment Status {#invoice-status}

Using this request you can get current payment status of the invoice.

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
- Authorization: Basic ***

Response ←

Successful 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": "paid",
        "error": 0,
        "user": "tel:+79031234567",
        "comment": "Text comment"
     }
  }
}

Error response

HTTP/1.1 500 Internal Server Error
Content-Type: text/json

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

Fields

Response field	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 to two decimals
bill.originAmount	String	The amount taken from the balance when the invoice get paid (see `originCcy` parameter). The number is rounded down to two decimals. Returned 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). Returned 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

Operation Statuses {#status}

Payment Status {#status_bills}

Status	Description	Final
waiting	Payment initiating, pending payment	N
paid	paid	Y
rejected	rejected	Y
unpaid	Payment processing error. Not paid	Y
expired	Payment expired. Not paid	Y

Error Codes {#errors}

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 returned 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
1001	Currency is not allowed for the merchant	Y
1003	No convert rate for these currencies	N
1019	Unable to determine wireless operator for MNO balance payment	Y
1419	Bill was already payed	Y

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

pull-mobile-payments_en.html.md

pull-mobile-payments_en.html.md

Payments From Mobile Account

Edit on GitHub

Customer Order Payment Flow {#steps}

Authorization {#auth_param}

Authorization and forms

Service data {#auth_param}

Details

Payment Initiation {#invoice_rest}

Request → PUT

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

HEADERS

Parameters

Response ←

Fields

Checking Payment Status {#invoice-status}

Request → GET

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

HEADERS

Response ←

Fields

Operation Statuses {#status}

Payment Status {#status_bills}

Error Codes {#errors}

Files

pull-mobile-payments_en.html.md

Latest commit

History

pull-mobile-payments_en.html.md

File metadata and controls

Payments From Mobile Account

Edit on GitHub

Customer Order Payment Flow {#steps}

Authorization {#auth_param}

Authorization and forms

Service data {#auth_param}

Details

Payment Initiation {#invoice_rest}

Request → PUT

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

HEADERS

Parameters

Response ←

Fields

Checking Payment Status {#invoice-status}

Request → GET

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

HEADERS

Response ←

Fields

Operation Statuses {#status}

Payment Status {#status_bills}

Error Codes {#errors}