Прием платежей через терминалы QIWI
Этот способ оплаты позволяет торговцам принимать оплату за товары и услуги через терминалы QIWI, а также в тех салонах связи, магазинах электроники и кассах банков, которые являются партнерами QIWI.
Когда покупатели оплачивают заказы через терминалы QIWI, торговцы получают уведомление от системы bePaid о приеме платежа таким способом. Дополнительно, торговцы могут увидеть краткую информацию о таких платежах в личном кабинете системы bePaid и получить ее в отчете о транзакциях.
Info
Для приема платежей этим способом оплаты торговец должен быть зарегистирован в системах bePaid и QIWI.
Процесс приема платежей через терминалы QIWI
Шаг | Описание |
---|---|
1 | Покупатель выбирает товар или услугу торговца к оплате через терминал QIWI. |
2 | QIWI направляет запрос на подтверждение приема платежа от покупателя в систему bePaid. |
3 | bePaid регистрирует транзакцию и отправляет запрос на подтверждение приема платежа от покупателя торговцу. |
4 | Торговец обрабатывает запрос согласно Правилам взаимодействия и подтверждает прием платежа от покупателя в ответе на запрос системы bePaid. |
5 | bePaid подтверждает платеж системе QIWI. |
6 | QIWI Terminal выводит на экране информацию о том, что платеж может быть проведен. |
7 | Покупатель проводит оплату. |
8 | QIWI уведомляет bePaid о проведении транзакции и ее статусе. |
9 | bePaid сохраняет информацию о транзакции и высылает торговцу автоматическое уведомление о статусе платежа. |
Правила взаимодействия
-
Обмен данными между приложением торговца и bePaid проходит по принципу взаимодействия с RESTful API. Инициатором запроса является bePaid, а отвечающей стороной – торговец.
-
Приложение торговца принимает запросы по протоколу HTTPS с IP-адресов bePaid.
Info
Для получения актуального списка IP-адресов bePaid обратитесь к вашему менеджеру.
-
Приложение торговца поддерживает следующие конечные точки:
-
Account Verification URL - конечная точка, которая валидирует идентификаторы покупателей и подтверждает прием платежа от них. На эту точку bePaid будет посылать запрос на подтверждение платежа;
-
Notification URL - конечная точка, которая принимает уведомления. На эту точку bePaid будет высылать уведомление со статусом и данными платежа через терминал QIWI.
-
-
Конечные точки поддерживают авторизацию запросов типа
Basic
сShop ID
иSecret Key
как имя пользователя и пароль соответственно. Параметры авторизации запроса передаются в заголовкеAuthorization
. Информацию оShop ID
иSecret key
магазина можно найти здесь. -
Помимо заголовка
Authorization
, запрос на конечную точку Notification URL содержит заголовокContent-Signature
c RSA цифровой подписью для проверки уведомления. -
Приложение торговца обрабатывает запросы методом POST с параметрами в теле запроса в формате JSON. Схемы параметров приведена ниже.
-
Ответ на запрос к конечной точке 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"
}