Вопросы
bss@qiwi.com
NAV
shell Node.js SDK PHP SDK Java SDK Popup .Net SDK

API QIWI Кассы

Последнее обновление: 2019-03-20 | Редактировать на GitHub

API QIWI Кассы открывает доступ к операциям с выставляемыми счетами. Счет - универсальная заявка на оплату. По умолчанию пользователю доступно несколько способов оплаты. В API поддерживаются операции выставления и отмены счетов, возврата средств по оплаченным счетам, а также проверки статуса выполнения операций.

Для работы API потребуются публичный и секретный ключи. Ключи создаются в личном кабинете после регистрации и подключения на kassa.qiwi.com или p2p.qiwi.com.

Схема работы

Operation Flow

Авторизация

Запросы мерчанта авторизуются посредством секретного ключа API (SECRET_KEY). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как “Bearer SECRET_KEY”.

Публичный ключ (PUBLIC_KEY) используется для выставления счетов через веб-форму.

Ключи создаются в личном кабинете после регистрации и подключения на kassa.qiwi.com или p2p.qiwi.com.

const QiwiBillPaymentsAPI = require('bill-payments-node-js-sdk');

const SECRET_KEY = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

const qiwiApi = new QiwiBillPaymentsAPI(SECRET_KEY);
--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"
<?php

const SECRET_KEY = 'eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments = new Qiwi\Api\BillPayments(SECRET_KEY);

?>
String secretKey = "eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************";
 BillPaymentClient client = BillPaymentClientFactory.createDefault(secretKey);
var secretKey = "eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjUyNjgxMiwiYXBpX3VzZXJfaWQiOjcxNjI2MTk3LCJzZWNyZXQiOiJmZjBiZmJiM2UxYzc0MjY3YjIyZDIzOGYzMDBkNDhlYjhiNTnONPININONPN090MTg5Z**********************";

var client = BillPaymentClientFactory.createDefault(secretKey);

Взаимодействие через API

1. Выставление счета

Надежный способ для интеграции. Параметры передаются server2server с использованием авторизации. Метод позволяет выставить счет, при успешном выполнении запроса в ответе вернется параметр payUrl - ссылка для редиректа пользователя на платежную форму.

Также существует способ выставления счета через платежную форму

Возможности при открытии ссылки счета

Запрос → PUT

const billId = '893794793973';

const fields = {
    amount: 1.00,
    currency: 'RUB',
    comment: 'Hello world',
    expirationDateTime: '2018-03-02T08:44:07+03:00'
};

qiwiRestApi.createBill( billId, fields ).then( data => {
    //do with data
});
curl https://api.qiwi.com/partner/bill/v1/bills/893794793973
-X PUT
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {}  
   }
<?php

$billId = '893794793973';
$fields = [
  'amount' => 1.00,
  'currency' => 'RUB',
  'comment' => 'test',
  'expirationDateTime' => '2018-03-02T08:44:07+03:00',
  'email' => 'example@mail.org',
  'account' => 'client4563'
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->createBill($billId, $fields);

print_r($response);

?>
CreateBillInfo billInfo = new CreateBillInfo(
                UUID.randomUUID().toString(),
                new MoneyAmount(
                        BigDecimal.valueOf(199.90),
                        Currency.getInstance("RUB")
                ),
                "comment",
                ZonedDateTime.now().plusDays(45),
                new Customer(
                        "example@mail.org",
                        UUID.randomUUID().toString(),
                        "79123456789"
                ),
                "http://merchant.ru/success"
        );
BillResponse response = client.createBill(billInfo);
client.CreateBill(
    info: new CreateBillInfo
    {
        BillId = Guid.NewGuid().ToString(),
        Amount = new MoneyAmount
        {
            ValueDecimal = 199.9m,
            CurrencyEnum = CurrencyEnum.Rub
        },
        Comment = "comment",
        ExpirationDateTime = DateTime.Now.AddDays(45),
        Customer = new Customer
        {
            Email = "example@mail.org",
            Account = Guid.NewGuid().ToString(),
            Phone = "79123456789"
        },
        SuccessUrl = new Uri("http://merchant.ru/success")
    },
    customFields: new CustomFields
    {
        ThemeCode = "кодСтиля"
    }
);
Параметр Описание Тип Обяз.
billId Уникальный идентификатор счета в системе мерчанта string +
amount.value Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) +
amount.currency Валюта счета (Alpha-3 ISO 4217 код) +
phone Номер телефона пользователя, на который выставляется счет (в международном формате) string -
email E-mail пользователя, куда будет отправлена ссылка для оплаты счета string -
account Идентификатор пользователя в системе мерчанта string -
comment Комментарий к счету String(255) -
customFields[] Дополнительные данные счета String(255) -
expirationDateTime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна.
URL-закодированная строка
ГГГГ-ММ-ДДTччмм+\-чч:мм
+

Ответ ←

Пример тела ответа

  {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
  }

Пример тела ответа при ошибке

{
	"serviceName": "invoicing-api",
	"errorCode": "auth.unauthorized",
	"description": "Неверные аутентификационные данные",
	"userMessage": "",
	"datetime": "2018-04-09T18:31:42+03:00",
	"traceId" : "48485a395dfsdf34v124"
}

Параметр Тип Описание
billId String Уникальный идентификатор счета в системе мерчанта
siteId String Идентификатор сайта мерчанта в QIWI Кассе
amount Object Данные о сумме счета
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Валюта счета (Alpha-3 ISO 4217 код)
status Object Данные о статусе счета
status.value String Текущий статус счета
status.changedDateTime String Дата обновления статуса. Формат даты:
YYYY-MM-DDThh:mm:ss±hh
customFields Object Дополнительные поля
customer Object Идентификаторы пользователя. Возможные опции: email, phone, account
comment String Комментарий к счету
creationDateTime String Системная дата создания счета. Формат даты:
YYYY-MM-DDThh:mm:ss
payUrl String Ссылка на созданную платежную форму
expirationDateTime String Срок действия созданной формы для оплаты. Формат даты:
YYYY-MM-DDThh:mm:ss+\-hh:mm

2. Уведомления об оплате счетов

Пример уведомления

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
X-Api-Signature-SHA256: J4WNfNZd***V5mv2w=
Host: server.ru

{ "bill":
  {  
     "siteId":"23044",
     "billId":"1519892138404fhr7i272a2",
     "amount":{  
        "value":"100",
        "currency":"RUB"
     },
     "status":{  
        "value":"PAID",
        "datetime":"2018-03-01T11:16:12"
     },
     "customer":{},
     "customFields":{},
     "creationDateTime":"2018-03-01T11:15:39",
     "expirationDateTime":"2018-04-01T11:15:39+03:00"
   },
  "version":"1"
}

Уведомление представляет собой входящий POST-запрос. Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8). Aдрес сервера для уведомлений указывается на сайте kassa.qiwi.com в разделе “Настройка протокола” или на p2p.qiwi.com при генерации ключей.

Авторизация уведомлений

После получения входящего уведомления необходимо проверить подлинность данного уведомления. Для этого используется механизм цифровой подписи. Подпись уведомления отправляется в заголовке X-Api-Signature-SHA256. Для формирования подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256.

Алгоритм проверки подписи:

  1. Объединить значения параметров в одну строку с разделителем |:

    invoice_parameters = {amount.currency}|{amount.value}|{billId}|{siteId}|{status.value}

    где {*} – значение параметра уведомления. Все значения при проверке подписи должны трактоваться как строки.

  2. Вычислить HMAC-хэш c алгоритмом хэширования SHA256:

    hash = HMAС(SHA256, invoice_parameters, secret_key) Где:

    • secret_key – ключ функции ;
    • invoice_parameters – строка из п.1;
  3. Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.

const validSignatureFromNotificationServer =
      '07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b';

const notificationData = {
    bill: {
        siteId: 'test',
        billId: 'test_bill',
        amount: { value: 1, currency: 'RUB' },
        status: { value: 'PAID', datetime: '2018-03-01T11:16:12+03' },
        customer: {},
        customFields: {},
        creationDateTime: '2018-03-01T11:15:39+03:',
        expirationDateTime: '2018-04-15T11:15:39+03'
    },
    version: '1'
};

const merchantSecret = 'test-merchant-secret-for-signature-check';

qiwiApi.checkNotificationSignature(
    validSignatureFromNotificationServer, notificationData, merchantSecret
); // true
<?php

$validSignatureFromNotificationServer = '07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b';
$notificationData = [
  'bill' => [
    'siteId' => 'test',
    'billId' => 'test_bill',
    'amount' => ['value' => 1, 'currency' => 'RUB'],
    'status' => ['value' => 'PAID']
  ],
  'version' => '3'
];
$merchantSecret = 'test-merchant-secret-for-signature-check';

/** @var \Qiwi\Api\BillPayments $billPayments */
$billPayments->checkNotificationSignature(
  $validSignatureFromNotificationServer, $notificationData, $merchantSecret
); // true

?>
String merchantSecret = "test-merchant-secret-for-signature-check";
Notification notification = new Notification(
        new Bill(
                "test",
                "test_bill",
                new MoneyAmount(
                        BigDecimal.ONE,
                        Currency.getInstance("RUB")
                ),
                BillStatus.PAID
        ),
        "3"
);
String validSignature = "07e0ebb10916d97760c196034105d010607a6c6b7d72bfa1c3451448ac484a3b";
 BillPaymentsUtils.checkNotificationSignature(validSignature, notification, merchantSecret); //true

Cтрока и ключ подписи кодируются в UTF-8.

Параметр Описание Тип
bill Данные о счете Object
billId Уникальный идентификатор счета в системе мерчанта String(200)
siteId Идентификатор сайта мерчанта в QIWI Кассе String
amount Данные о сумме счета Object
amount.value Сумма счета, округленная до двух десятичных знаков в меньшую сторону Number(6.2)
amount.currency Идентификатор валюты счета (Alpha-3 ISO 4217 код) String(3)
status Данные о статусе счета Object
status.value Строковое значение статуса String
status.changedDateTime Дата обновления статуса. Формат даты
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
String
customer Данные о пользователе, на которого был выставлен счет Object
customer.phone Номер телефона, на который был выставлен счет (если был указан при выставлении счета) String
customer.email E-mail пользователя (если был указан при выставлении счета) String
customer.account Идентификатор пользователя в системе мерчанта (если был указан при выставлении счета) String
creationDateTime Дата создания счета. Формат даты
ГГГГ-ММ-ДДTЧЧ:ММ:ССZ
String
expirationDateTime Срок оплаты счета. Формат даты
ГГГГ-ММ-ДДTЧЧ:ММ:СС+ЧЧ:ММ\-Z
String
comment Комментарий к счету String(255)
customFields Дополнительные данные счета (если были указаны при выставлении счета). Object
version Версия уведомлений String

Ответ → POST

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

{
 "error":"0"
}

После того, как был получен входящий запрос-уведомление, необходимо проверить подлинность цифровой подписи и отправить ответ в формате JSON. В ответе должен вернуться код результата обработки уведомления. Код результата должен находиться в параметре error.

Заголовки

3. Проверка статуса оплаты счета

Метод предназначен для получения статуса оплаты счета клиентом. Рекомендуется его использовать после получения уведомления об оплате.

Запрос → GET

const billId = '893794793973';

qiwiApi.getBillInfo(billId).then( data => {
    //do with data
});
curl https://api.qiwi.com/partner/bill/v1/bills/893794793973
-X GET
-H 'Accept: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
<?php

$billId = '893794793973';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->getBillInfo($billId);

print_r($response);

?>
String billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
 BillResponse response = client.getBillInfo(billId);
var billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";

var response = client.getBillInfo(billId);

Ответ ←

Пример тела ответа

  {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
  }

Пример тела ответа при ошибке

{
	"serviceName": "invoicing",
	"errorCode": "auth.unauthorized",
	"description": "Неверные аутентификационные данные",
	"userMessage": "",
	"datetime": "2018-04-09T18:31:42+03:00",
	"traceId" : ""
}
Параметр Тип Описание
billId String Уникальный идентификатор счета в системе мерчанта
siteId String Идентификатор сайта мерчанта в QIWI Кассе
amount Object Данные о сумме счета
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону.
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status Object Данные о статусе счета
status.value String Текущий статус счета
status.changedDateTime String Дата обновления статуса
customFields Object Объект строковых дополнительных параметров, переданных партнером
customer Object Идентификаторы пользователя
customer.phone String Номер телефона, на который был выставлен счет (если был указан при выставлении счета)
customer.email String E-mail пользователя (если был указан при выставлении счета)
customer.account String Идентификатор пользователя в системе мерчанта (если был указан при выставлении счета)
comment String Комментарий к счету
creationDateTime String Системная дата создания счета. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс
payUrl String Ссылка для переадресации пользователя на созданную платежную форму
expirationDateTime String Срок действия созданной формы для оплаты. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм

4. Отмена неоплаченного счета

Запрос → POST

const bill_id = '893794793973';

qiwiApi.cancelBill(billId).then( data => {
    //do with data
});
curl https://api.qiwi.com/partner/bill/v1/bills/893794793973/reject
-X POST
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
<?php

$billId = '893794793973';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->cancelBill($billId);

print_r($response);

?>
String billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
 BillResponse response = client.cancelBill(billId);
var billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";

var response = client.cancelBill(billId);

Ответ ←

Пример тела ответа

 {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 2.42,
      "currency": "RUB"
    },
    "status": {
      "value": "REJECTED",
      "changedDateTime": "2018-02-28T11:43:23.386+03:00"
    },
    "customer": {
      "email": "test@qiwi.com",
      "phone": "79191234567",
      "account": "user_account"
    },
    "customFields": {
      "city": "Moscow"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-02-28T11:43:23.612+03:00",
    "expirationDateTime": "2018-04-14T11:43:23+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=6848dd49-e260-4343-b258-62199cffe8c1"
  }

Пример тела ответа при ошибке

{
	"serviceName": "invoicing",
	"errorCode": "auth.unauthorized",
	"description": "Неверные аутентификационные данные",
	"userMessage": "",
	"datetime": "2018-04-09T18:31:42+03:00",
	"traceId" : ""
}
Параметр Тип Описание
billId String Уникальный идентификатор счета в системе мерчанта
siteId String Идентификатор сайта мерчанта в QIWI Кассе
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status Object Данные о статусе счета
status.value String Текущий статус счета
status.changedDateTime String Дата обновления статуса. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм
customFields Object Объект строковых дополнительных параметров, переданных партнером
customer Object Идентификаторы пользователя. Возможные опции: email, phone, account
comment String Комментарий к счету
creationDateTime String Системная дата создания счета. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс
payUrl String Ссылка на созданную платежную форму
expirationDateTime String Срок действия созданной формы для оплаты. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм

5. Возврат средств

Метод позволяет сделать возврат средств.

Запрос → PUT

const billId = '893794793973';
const refundId = '899343443';
const amount = 12;
const currency = 'RUB'

qiwiApi.refund(billId, refundId, amount, currency).then( data => {
    //do with data
});

curl https://api.qiwi.com/partner/bill/v1/bills/893794793973/refunds/899343443
-X PUT
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
    "amount": {
    "currency": "RUB",
    "value": 1
    }
}'
<?php

$billId = '893794793973';
$refundId = '899343443';
$amount = 12;
$currency = 'RUB';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->refund($billId, $refundId, $amount, $currency);

print_r($response);
?>
String billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
String refundId = UUID.randomUUID().toString();
MoneyAmount amount = new MoneyAmount(
        BigDecimal.valueOf(104.90),
        Currency.getInstance("RUB")
);
 RefundResponse refundResponse = client.refundBill(paidBillId, refundId, amount);
var billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
var refundId = Guid.NewGuid().ToString();
var amount = new MoneyAmount
{
    ValueDecimal = 104.9m,
    CurrencyEnum = CurrencyEnum.Rub
};

var refundResponse = client.refundBill(paidBillId, refundId, amount);

Ответ ←

Пример тела ответа

{
    "amount": {
      "value": 50.50,
      "currency": "RUB"
    },
    "datetime": "2018-03-01T16:06:57+03",
    "refundId": "1",
    "status": "PARTIAL"
}

Пример тела ответа при ошибке

{
	"serviceName": "invoicing",
	"errorCode": "refund.incorrect.amount",
	"description": "Неверная сумма возврата",
	"userMessage": "Неверная сумма возврата",
	"datetime": "2005-08-09T18:31:42+03:00",
	"traceId" : ""
}
Параметр Тип Описание
datetime String Если ответ содержит ошибку: Системная дата обработки запроса
refundId String Уникальный идентификатор возврата в системе мерчанта
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status String Статус возврата
datetime String Системная дата проведения возврата. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс+hh

6. Статус возврата

Метод запрашивает статус возврата.

Запрос → GET

const billId = '893794793973';
const refundId = '899343443';

qiwiApi.getRefundInfo(billId, refundId).then( data => {
    //do with data
});
curl https://api.qiwi.com/partner/bill/v1/893794793973/refund/899343443
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
<?php

$billId = '893794793973';
$refundId = '899343443';

/** @var \Qiwi\Api\BillPayments $billPayments */
$response = $billPayments->getRefundInfo($billId, $refundId);

print_r($response);

?>
String billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
String refundId = '3444e8ca-cf68-4dbd-92ee-f68c4bf8f29b';
 RefundResponse response = client.getRefundInfo(paidBillId, refundId);
var billId = "fcb40a23-6733-4cf3-bacf-8e425fd1fc71";
var refundId = "3444e8ca-cf68-4dbd-92ee-f68c4bf8f29b";

var response = client.getRefundInfo(paidBillId, refundId);

Ответ ←

Пример тела ответа

{
    "amount": {
      "value": 50.50,
      "currency": "RUB"
    },
    "datetime": "2018-03-01T16:06:57+03",
    "refundId": "1",
    "status": "PARTIAL"
}

Пример тела ответа при ошибке

{
	"serviceName": "invoicing",
	"errorCode": "refund.incorrect.amount",
	"description": "Неверная сумма возврата",
	"userMessage": "Неверная сумма возврата",
	"datetime": "2005-08-09T18:31:42+03:00",
	"traceId" : ""
}
Параметр Тип Описание
datetime String Если ответ содержит ошибку: Системная дата обработки запроса
refundId String Уникальный идентификатор возврата в системе мерчанта
amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
status String Статус возврата
datetime String Системная дата проведения возврата. Формат даты:
ГГГГ-ММ-ДДTчч:мм:сс+hh

Статусы оплаты счетов

Статус Описание Финальный
WAITING Счет выставлен, ожидает оплаты -
PAID Счет оплачен +
REJECTED Счет отклонен +
EXPIRED Время жизни счета истекло. Счет не оплачен +

Статусы операции возврата

Статус Описание Финальный
PARTIAL Частичный возврат суммы -
FULL Полный возврат суммы +

Дополнительно

Выставление счета через платежную форму

Простой способ для интеграции. При открытии формы клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается платежная форма с выбором способа оплаты. При использовании этого способа нельзя гарантировать, что все счета выставлены мерчантом, в отличие от выставления по API.

REDIRECT →

const publicKey = 'Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******';

const params = {
    publicKey,
    amount: 42.24,
    billId: '893794793973',
    successUrl: 'http://test.ru/',
    email: 'm@ya.ru'
};

const link = qiwiApi.createPaymentForm(params);
curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&billId=893794793973&successUrl=http%3A%2F%2Ftest.ru%3F&email=m@ya.ru
<?php

$publicKey = '2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zf******';
$params = [
  'publicKey' => $publicKey,
  'amount' => 200,
  'billId' => '893794793973'
];

/** @var \Qiwi\Api\BillPayments $billPayments */
$link = $billPayments->createPaymentForm($params);

echo $link;

?>
String publicKey = "2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc";
 MoneyAmount amount = new MoneyAmount(
        BigDecimal.valueOf(499.90),
        Currency.getInstance("RUB")
);
String billId = UUID.randomUUID().toString();
String successUrl = "https://merchant.com/payment/success?billId=893794793973";
 String paymentUrl = client.createPaymentForm(new PaymentInfo(key, amount, billId, successUrl));
var publicKey = "2tbp1WQvsgQeziGY9vTLe9vDZNg7tmCymb4Lh6STQokqKrpCC6qrUUKEDZAJ7mvFnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypdXCbQJqHEJW5RJmKfj8nvgc";

var amount = new MoneyAmount
{
    ValueDecimal = 499.9m,
    CurrencyEnum = CurrencyEnum.Rub
};
var billId = Guid.NewGuid().ToString();
var successUrl = "https://merchant.com/payment/success?billId=893794793973";

var paymentUrl = client.createPaymentForm(new PaymentInfo(key, amount, billId, successUrl));
Параметр Описание Тип Обяз.
publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String +
billId Уникальный идентификатор счета в системе мерчанта URL-закодированная строка String(200) -
amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) -
phone Номер телефона пользователя, на который выставляется счет (в международном формате) URL-закодированная строка -
email E-mail пользователя, куда будет отправлена ссылка для оплаты счета URL-закодированная строка -
account Идентификатор пользователя в системе мерчанта URL-закодированная строка -
comment Комментарий к счету URL-закодированная строка String(255) -
customFields[] Дополнительные данные счета URL-закодированная строка String(255) -
lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна.
Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус
URL-закодированная строка
ГГГГ-ММ-ДДTччмм
-
successUrl URL для переадресации в случае успешной оплаты с баланса QIWI Кошелька. При ином способе оплаты переадресация не выполняется. Ссылка должна вести на сайт мерчанта. URL-закодированная строка -

Персонализация

Персонализация позволяет создать платежную форму под ваш стиль. Настраивается лого, фон и цвет кнопок.

Создать стили можно в личном кабинете на kassa.qiwi.com, при настройке задается параметр кодСтиля, который передается в запросе на создание счета. Возможно создать несколько стилей. В запросе необходимо передавать переменную: "themeCode":"кодСтиля" в параметре customFields.

Пример передачи параметра при работе с формой

curl https://oplata.qiwi.com/create?publicKey=Fnzr1yTebUiQaBLDnebLMMxL8nc6FF5zfmGQnypc*******&amount=100&billId=893794793973&successUrl=http%3A%2F%2Ftest.ru%3F&customFields[themeCode]=кодСтиля

Пример передачи параметра при работе через API

curl https://api.qiwi.com/partner/bill/v1/bills/893794793973
-X PUT
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {"themeCode":"кодСтиля"}
   }

Customer form

Всплывающее окно (popup), позволяет открыть форму оплаты поверх вашего сайта. В библиотеке доступно два метода: создание нового счета и открытие существующего.

Скачать библиотеку QIWI Checkout Popup

Установка и подключение:
<script src='https://oplata.qiwi.com/popup/v1.js'></script>

Выставление нового счета

Метод QiwiCheckout.createInvoice

Пример выставления счета через popup

QiwiCheckout.createInvoice({
    publicKey: '5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3c******',
    amount: 1.23,
    phone: '79123456789',
})
    .then(data => {
        //  data === {
        //    publicKey: '5nAq6abtyCz4tcDj89e5w7Y5i524LAFmzrsN6bQTQ3c******',
        //    amount: 1.23,
        //    phone: '79123456789',
        //  }
    })
    .catch(error => {
        //  error === {
        //      reason: "PAYMENT_FAILED"
        //  }
    })

Пример оплаты

Параметр Описание Тип Обязательное
publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String +
amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) +
phone Номер телефона пользователя, на который выставляется счет (в международном формате) String -
email E-mail пользователя, куда будет отправлена ссылка для оплаты счета String -
account Идентификатор пользователя в системе мерчанта String -
comment Комментарий к счету String(255) -
customFields Дополнительные данные счета Object -
lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. Строка в виде ГГГГ-ММ-ДДTччмм -

Открытие существующего счета

Метод QiwiCheckout.openInvoice

Пример открытия уже созданного счета в popup

params = {
    payUrl: 'https://oplata.qiwi.com/form?invoiceUid=06df838c-0f86-4be3-aced-a950c244b5b1'
}

QiwiCheckout.openInvoice(params)
    .then(data => {
        // ...
    })
    .catch(error => {
        // ...
    })
Параметр Описание Тип Обязательное
payUrl URL инвойса String +

Возможности при открытии ссылки счета

При выставлении счета через API в ответ приходит url с формой для оплаты, к нему можно добавить следующие параметры:

Параметр Описание Тип
paySource При открытии формы сразу будет выбран способ оплаты. Возможные значения:
qw
card
mobile
sovest
Если способ оплаты недоступен - выбирается рекомендуемый способ оплаты
String
successUrl URL для переадресации в случае успешной оплаты с баланса QIWI Кошелька. При ином способе оплаты переадресация не выполняется. Ссылка должна вести на сайт мерчанта. Object
lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. String
ГГГГ-ММ-ДДTччмм

Готовые решения

SDK и библиотеки

Решения для CMS

Рекомендации к оформлению

Иконки

Данные рекомендации помогут вашим пользователям быстрее сориентироваться на странице выбора способов оплаты.

Operation Flow

Допустимо отображение QIWI Кассы текстом, без логотипа. Иконки способов оплаты выводятся:

Operation Flow

Operation Flow

Логотипы для скачивания

Скачать логотип QIWI Кассы

Скачать иконки способов оплаты