Перейти к содержанию

Прием платежей через терминалы QIWI

Этот способ оплаты позволяет торговцам принимать оплату за товары и услуги через терминалы QIWI, а также в тех салонах связи, магазинах электроники и кассах банков, которые являются партнерами QIWI.

Когда покупатели оплачивают заказы через терминалы QIWI, торговцы получают уведомление от системы bePaid о приеме платежа таким способом. Дополнительно, торговцы могут увидеть краткую информацию о таких платежах в личном кабинете системы bePaid и получить ее в отчете о транзакциях.

Info

Для приема платежей этим способом оплаты торговец должен быть зарегистирован в системах bePaid и QIWI.

Процесс приема платежей через терминалы QIWI

Схема приема платежа через терминал QIWI

Шаг Описание
1 Покупатель выбирает товар или услугу торговца к оплате через терминал QIWI.
2 QIWI направляет запрос на подтверждение приема платежа от покупателя в систему bePaid.
3 bePaid регистрирует транзакцию и отправляет запрос на подтверждение приема платежа от покупателя торговцу.
4 Торговец обрабатывает запрос согласно Правилам взаимодействия и подтверждает прием платежа от покупателя в ответе на запрос системы bePaid.
5 bePaid подтверждает платеж системе QIWI.
6 QIWI Terminal выводит на экране информацию о том, что платеж может быть проведен.
7 Покупатель проводит оплату.
8 QIWI уведомляет bePaid о проведении транзакции и ее статусе.
9 bePaid сохраняет информацию о транзакции и высылает торговцу автоматическое уведомление о статусе платежа.

Правила взаимодействия

  1. Обмен данными между приложением торговца и bePaid проходит по принципу взаимодействия с RESTful API. Инициатором запроса является bePaid, а отвечающей стороной – торговец.

  2. Приложение торговца принимает запросы по протоколу HTTPS с IP-адресов bePaid.

    Info

    Для получения актуального списка IP-адресов bePaid обратитесь к вашему менеджеру.

  3. Приложение торговца поддерживает следующие конечные точки:

    • Account Verification URL - конечная точка, которая валидирует идентификаторы покупателей и подтверждает прием платежа от них. На эту точку bePaid будет посылать запрос на подтверждение платежа;

    • Notification URL - конечная точка, которая принимает уведомления. На эту точку bePaid будет высылать уведомление со статусом и данными платежа через терминал QIWI.

  4. Конечные точки поддерживают авторизацию запросов типа Basic с Shop ID и Secret Key как имя пользователя и пароль соответственно. Параметры авторизации запроса передаются в заголовке Authorization. Информацию о Shop ID и Secret key магазина можно найти здесь.

  5. Помимо заголовка Authorization, запрос на конечную точку Notification URL содержит заголовок Content-Signature c RSA цифровой подписью для проверки уведомления.

  6. Приложение торговца обрабатывает запросы методом POST с параметрами в теле запроса в формате JSON. Схемы параметров приведена ниже.

  7. Ответ на запрос к конечной точке Account Verification URL передает параметры в формате JSON в кодировке UTF-8. Скорость ответа не должна превышать 14 секунд. В противном случае bePaid разрывает соединение по таймауту.

    Info

    Для тестирования интеграции с этим способом оплаты и ее использования сообщите менеджеру bePaid следующие параметры:

    • URL созданных конечных точек Account Verification URL и Notification URL;

    • регулярное выражение для валидации формата идентификаторов покупателей (номеров лицевых счетов, телефонов, адресов электронной почты и т.д.);

    • тестовый идентификатор покупателя, отвечающий регулярному выражению, для тестирования интеграции.


Подтверждение платежа

Запрос

Для подтверждения приема платежа через терминал QIWI bePaid отправляет POST- запрос на URL созданной конечной точки Account Verification URL, который имеет:

  • заголовки Accept: application/json и Content-type: application/json;
  • авторизацию типа Basic с Shop ID и Secret key магазина;
  • тело запроса в формате JSON со следующими параметрами:
Параметр Тип данных Описание
request object Секция параметров запроса.
amount * обязательный
integer Сумма платежа в минимальных денежных единицах.
currency * обязательный
string (3) Валюта платежа в формате ISO-4217.
method_type * обязательный
string qiwi_terminal
account * обязательный
string Уникальный идентификатор покупателя в системе торговца (номер лицевого счета, телефона, адрес электронной почты и т.д.).
Пример запроса
{
  "request":{     
    "amount":100,
    "currency":"RUB",
    "method_type":"qiwi_terminal",
    "account":"customer@example.com"
  }
}
Ответ

Ответ на запрос должен сооответствовать Правилам взаимодействия и иметь следующие параметры:

Параметр Тип данных Описание
response object Секция параметров ответа.
result * обязательный
integer Код результата обработки или ошибки запроса.

Возможные значения смотрите в таблице Коды результатов обработки запроса.
Пример ответа
{
  "response":{
    "result":"0"
  }
}
Коды результатов обработки запроса

В зависимости от результата обработки запроса на подтверждение приема платежа передайте как значение параметра ответа result один из кодов согласно следующей таблице:

Код Описание
0 OK
1 Временная ошибка. Повторите запрос позже.
4 Неверный формат идентификатора абонента.
5 Идентификатор абонента не найден. Ошибка номера.
7 Прием платежа запрещен торговцем.
8 Прием платежа запрещен по техническим причинам.
243 Невозможно проверить состояние счета.
300 Прочая ошибка.

Warning

"result":"0" в ответе на запрос относится только к согласию торговца принять платеж от покупателя. После того, как провайдер способа оплаты обработает платеж, транзакция может получить как статус successful, так и статус failed.


Уведомление о статусе транзакции

После проведения платежа этим способом bePaid высылает торговцу автоматическое уведомление о статусе транзакции на URL созданной конечной точки Notification URL.

Помимо стандартных параметров транзакции уведомление содержит следующие дополнительные параметры о способе оплаты:

Параметр Тип данных Описание
qiwi_terminal object Секция параметров способа оплаты.
type * обязательный
string qiwi_terminal
account_number * обязательный
string Уникальный идентификатор покупателя в системе торговца (номер лицевого счета, телефона, адрес электронной почты и т.д.).
Пример уведомления
{
    "transaction": {
        "uid": "603a8710-c804-4600-a737-0266a907ab6c",
        "type": "payment",
        "status": "successful",
        "amount": 100,
        "currency": "RUB",
        "description": "Qiwi terminal payment for user account useremail@example.com",
        "created_at": "2023-04-12T10:48:15Z",
        "updated_at": "2023-04-12T10:56:52Z",
        "method_type": "qiwi_terminal",
        "receipt_url": "https://merchant.bepaid.by/customer/transactions/603a8710-c804-4600-a737-0266a907ab6c/803a200ece51d07c8710af14b409e7b270fdb2db4ec84e8d3f7614ddc25c569e",
        "payment": {
          "status": "successful",
          "gateway_id": 2000,
          "ref_id": "1234567890123",
          "message": "Transaction was successful"
        },
        "qiwi_terminal": {
          "type": "qiwi_terminal",
          "account_number": "useremail@example.com"
        },
        "customer": {
          "email": null,
          "ip": null
        },
        "message": "Transaction was successful",
        "test": false,
        "paid_at": "2023-04-12T10:56:52+00:00",
        "additional_data": {
          "payment_method": {
            "type": "alternative"
          }
        },
        "gateway": {
          "iframe": false
        }
    }
}

Тестирование интеграции

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

Запрос

Отправьте POST запрос на https://api.bepaid.by/beyag/testing/payment, который имеет:

  • заголовки Accept: application/json и Content-type: application/json;
  • авторизацию типа Basic с Shop ID и Secret Key магазина;
  • тело запроса в формате JSON со следующими параметрами:
Параметр Тип данных Описание
request object Секция параметров запроса.
amount * обязательный
integer Сумма платежа в минимальных денежных единицах.
currency * обязательный
string Валюта оплаты в формате ISO-4217.
method object Секция параметров платежного метода.
type * обязательный
string qiwi_terminal
account * обязательный
string Идентификатор покупателя в системе торговца (номер лицевого счета, телефона, адрес электронной почты и т.д.).

Возможные значения и ожидаемые статусы тестовых транзакций смотрите в таблице ниже.
test * обязательный
boolean Установите в значении true для проведения тестовой транзакции.
Значение параметра Ожидаемый статус транзакции
Валидный идентификатор покупателя successful, если в ответ на запрос на подтверждение платежа передан "result":"0". Эмуляция успешной обработки платежа на стороне провайдера.
Тестовый идентификатор покупателя failed, если в ответ на запрос на подтверждение платежа передан "result":"0". Эмуляция ошибки обработки платежа на стороне провайдера.
Ответ

После получения запроса система bePaid отправит ответ с HTTP кодом 200 или с сообщением об ошибке.

Пример ответа на тестовый запрос с идентификатором покупателя в неверном формате
{
  "message": "4 Wrong account format"
}