Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1067 lines (840 sloc) 43.5 KB
title search metatitle metadescription language_tabs services toc_footers
QIWI Универсальный платежный API 1.0.0 beta
true
Универсальный платежный API 1.0.0 beta
Универсальный платежный API открывает доступ к операциям с выставляемыми счетами. Счет - универсальная заявка на оплату. По-умолчанию пользователю доступно несколько способов оплаты. В API поддерживаются операции выставления и отмены счетов, возврата средств по оплаченным счетам, а также проверки статуса выполнения операций.
shell
javascript
Node.js SDK
php
PHP SDK
java
Java SDK
<a href='#'>Swagger</a> | <a href='#'>Qiwi Demo</a>
<a href='/'>На главную</a>
<a href='mailto:bss@qiwi.com'>Обратная связь</a>

Универсальный платежный API {#introduction}

Последнее обновление: 2018-10-08 | Редактировать на GitHub

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

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

Оформление

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

Operation Flow

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

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

Все варианты оформления в соответствующем разделе

SDK и библиотеки {#sdk}

  • NODE JS SDK - Готовое решение для разработки server2server интеграции c помощью Node.js.
  • PHP SDK - Готовое решение для разработки server2server интеграции c помощью PHP.
  • Java SDK - Готовое решение для разработки server2server интеграции c помощью Java.

Решения для CMS {#cms}

  • Wordpress - расширение под Woocommerce для работы с заказами
  • Онлайн Лейка - Wordpress расширение для благотворительности

Последовательность операций {#steps}

Operation Flow

  • Пользователь формирует заказ на сайте мерчанта.

  • Мерчант перенаправляет пользователя на Платежную форму для выставления счета по заказу. Или выставляет счет по API и перенаправляет пользователя на созданную платежную форму.

  • Пользователь выбирает способ оплаты и оплачивает счет. По умолчанию подбирается наиболее оптимальный способ оплаты.

  • После оплаты счета мерчант получает уведомление (предварительно настройте отправку уведомлений в Личном кабинете). Уведомления об оплате счета содержат параметры авторизации, которые необходимо проверять на сервере мерчанта.

  • Также есть возможность

Авторизация {#auth}

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

Важно! Не передавайте секретный ключ третьим лицам!.
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);

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

Простой способ для интеграции. При открытии формы клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается платежная форма с выбором способа оплаты. При использовании этого способа нельзя гарантировать, что все счета выставлены мерчантом, в отличие от выставления по 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));
  • Параметры

    В ссылке на веб-форму указываются параметры счета.

Параметр|Описание|Тип|Обяз. ---------|--------|---|---------|---|---- 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-закодированная строка|-

1.2 Выставление счета по API {#create}

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

Запрос → PUT

const billId = '893794793973';

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

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',
  '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);
  • URL https://api.qiwi.com/partner/bill/v1/bills/{billId}

      Параметры:
    • billId - уникальный идентификатор счета в системе мерчанта.
    • amount.currency - валюта счета (Alpha-3 ISO 4217 код).
    • amount.value - сумма счета, округленная до двух десятичных знаков в меньшую сторону.
    • comment - комментарий к счету.
    • expirationDateTime - срок оплаты счета. Время передается с указанием часового пояса.
    • customer.phone - номер телефона, на который был выставлен счет.
    • customer.email - e-mail пользователя.
    • customer.account - Идентификатор пользователя в системе мерчанта.
    • customFields - Дополнительные поля.
    •     </ul>
      </li>
    • HEADERS

      • Authorization: Bearer SECRET_KEY
      • Accept: application/json

    Ответ ←

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

      {
        "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",
        "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"
    }
    
    • HEADERS

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

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

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

    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"
       },
      "version":"1"
    }

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

    • HEADERS

      • X-Api-Signature-SHA256: ***
      • Accept: application/json
      • Content-type: application/json

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

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

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

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

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

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

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

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

      • 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.

    • Параметры

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

    Ответ → POST

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
     "error":"0"
    }

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

    Если в ответе код результата обработки уведомления отличается от 0 и/или код состояния HTTP отличается от 200 (OK), это интерпретируется как временная ошибка мерчанта. Сервер QIWI будет повторять запрос с нарастающим интервалом в течение суток.

    Заголовки

    • Content-type: application/json

    3. Проверка статуса оплаты счета {#invoice-status}

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

    Запрос → 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);
    • HEADERS

      • Authorization: Bearer SECRET_KEY
      • Accept: application/json

    Ответ ←

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

      {
        "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",
        "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" : ""
    }
    • HEADERS

      • Accept: application/json
    Параметр Тип Описание
    bill Object Данные о счете
    bill.billId String Уникальный идентификатор счета в системе мерчанта
    bill.siteId String Идентификатор сайта мерчанта в QIWI Кассе
    bill.amount Object Данные о сумме счета
    amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону.
    amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
    status Object Данные о статусе счета
    status.value String Текущий статус счета
    status.datetime Date Дата обновления статуса
    bill.customFields Object Объект строковых дополнительных параметров, переданных партнером
    bill.customer Object Идентификаторы пользователя
    customer.phone Номер телефона, на который был выставлен счет (если был указан при выставлении счета) String
    customer.email E-mail пользователя (если был указан при выставлении счета) String
    customer.account Идентификатор пользователя в системе мерчанта (если был указан при выставлении счета) String
    bill.comment String Комментарий к счету
    bill.creationDateTime Date Системная дата создания счета. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс
    bill.payUrl String Ссылка для переадресации пользователя на созданную платежную форму
    bill.expirationDateTime Date Срок действия созданной формы для оплаты. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс

    4. Отмена неоплаченного счета {#cancel}

    Запрос → 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);
    • HEADERS

      • Authorization: Bearer SECRET_KEY
      • Accept: application/json

    Ответ ←

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

    {
      "bill": {
        "siteId": "23044",
        "billId": "893794793973",
        "amount": {
          "value": 2.42,
          "currency": "RUB"
        },
        "status": {
          "value": "REJECTED",
          "datetime": "2018-02-28T11:43:23"
        },
        "customer": {
          "email": "test@qiwi.com",
          "phone": "79191234567",
          "account": "user_account"
        },
        "customFields": {
          "city": "Moscow"
        },
        "comment": "Text comment",
        "creationDateTime": "2018-02-28T11:43:23",
        "expirationDateTime": "2018-04-14T11:43:23",
        "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" : ""
    }
    • HEADERS

      • Accept: application/json
    Параметр Тип Описание
    bill Object Данные о счете
    bill.billId String Уникальный идентификатор счета в системе мерчанта
    bill.siteId String Идентификатор сайта мерчанта в QIWI Кассе
    amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
    amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
    status Object Данные о статусе счета
    status.value String Текущий статус счета
    status.datetime Date Дата обновления статуса
    bill.customFields Object Объект строковых дополнительных параметров, переданных партнером
    bill.customer Object Идентификаторы пользователя. Возможные опции: email, phone, account
    bill.comment String Комментарий к счету
    bill.creationDateTime Date Системная дата создания счета. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс
    bill.payUrl String Ссылка на созданную платежную форму
    bill.expirationDateTime Date Срок действия созданной формы для оплаты. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс

    5. Возврат средств {#refund}

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

    Запрос → 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);
    • URL https://api.qiwi.com/partner/bill/v1/bills/{billId}/refunds/{refundId}

        Параметры:
      • billId - уникальный идентификатор счета в системе мерчанта.
      • refundId - уникальный идентификатор возврата в системе мерчанта.
      • amount.value - сумма возврата.
      • amount.currency - валюта возврата.
    • HEADERS

      • Authorization: Bearer SECRET_KEY
      • Accept: application/json
      • application/json;charset=UTF-8

    Ответ ←

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

    {
        "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" : ""
    }
    • HEADERS

      • Accept: application/json
    Параметр Тип Описание
    datetime String Если ответ содержит ошибку: Системная дата обработки запроса
    refundId String Уникальный идентификатор возврата в системе мерчанта
    amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
    amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
    status String Статус возврата
    datetime Date Системная дата проведения возврата. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс+hh

    6. Статус возврата {#refund-status}

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

    Запрос → 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);
    • HEADERS

      • Authorization: Bearer SECRET_KEY
      • Accept: application/json
      • application/json;charset=UTF-8

    Ответ ←

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

    {
        "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" : ""
    }
    • HEADERS

      • Accept: application/json
    Параметр Тип Описание
    datetime String Если ответ содержит ошибку: Системная дата обработки запроса
    refundId String Уникальный идентификатор возврата в системе мерчанта
    amount.value Number Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
    amount.currency String Идентификатор валюты счета (Alpha-3 ISO 4217 код)
    status String Статус возврата
    datetime Date Системная дата проведения возврата. Формат даты:
    ГГГГ-ММ-ДДTчч:мм:сс+hh

    Статусы оплаты счетов {#status}

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

    Статусы операции возврата {#status_refund}

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

    Рекомендации по оформлению {#design}

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

    • Если платежный протокол QIWI — один из способов оплаты на вашем сайте, то мы рекомендуем выводить иконки всех способов оплаты, доступных на форме:

    Operation Flow

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

    Operation Flow

    • Если платежный протокол QIWI Кассы — единственный способ оплаты на вашем сайте, то упоминание QIWI Кассы в этом случае необязательно. Иконки способов оплаты, доступных на форме, в этом случае надо размещать под кнопкой оплаты:

    Operation Flow

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

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

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