Платежный терминал
Модуль periphery-models подключаемый через build.gradle содержит набор классов (моделей) результатов выполнения операций через платежный терминал.
Для каждого действия (action) используется своя модель результата операции, смотрите таблицу соответствия операций и моделей.
Модели передаются и получаются в виде json строки, которая является сериализованным представлением модели.
Чтобы сериализовать модель в json строку, необходимо использовать метод toJSON().
Для десериализации json строки в соответствующую модель следует использовать следующий метод (нужно указать необходимый класс модели):
kotlin
GSONConverter.fromJSON(data, PTTransaction::class.java)
java
GSONConverter.fromJSON(data, PTTransaction.class);
Таблица соответствия операций и моделей:
| Название операции | Действие (action) |
Модель результата операции |
|---|---|---|
| Оплата | ru.lifepay.checkout.payment_terminal.transaction.pay | PTTransaction |
| Возврат | ru.lifepay.checkout.payment_terminal.transaction.refund | PTTransaction |
| Отмена | ru.lifepay.checkout.payment_terminal.transaction.cancel | PTTransaction |
| Получение результата оплаты/возврата/отмены | ru.lifepay.checkout.payment_terminal.transaction.get_result | PTTransaction |
| Сверка итогов | ru.lifepay.checkout.payment_terminal.close_shift | PTSummaryShiftReport |
LIFE POS Checkout поддерживает несколько видов платежных терминалов. Каждый терминал поддерживает определенный набор операций. Перед использованием терминала его необходимо подключить на экране оборудования в приложении LIFE POS Checkout.
Платежные терминалы и поддерживаемые операции
| Платежный терминал | Тип подключения | Оплата/Возврат/Отмена | Получение результата оплаты/возврата/отмены | Сверка итогов |
|---|---|---|---|---|
| Lifepay QPOS | Bluetooth | + | + | Выполняется сервером в 00:00 |
| Сбербанк ICMP | Bluetooth | + | Только для оплаты | + |
Параметры входящего запроса
Оплата
Действие: ru.lifepay.checkout.payment_terminal.transaction.pay
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата оплаты по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных. |
| amount | Long | да | Сумма оплаты в копейках. |
Возврат
Действие: ru.lifepay.checkout.payment_terminal.transaction.refund
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата возврата по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных. |
| amount | Long | да | Сумма возврата в копейках. |
| primary_transaction | String | да | Сериализованный в json строку объект PTTransaction полученный в результатах оплаты. |
Отмена
Действие: ru.lifepay.checkout.payment_terminal.transaction.cancel
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата отмены по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных |
| amount | Long | да | Сумма отмены в копейках. |
| primary_transaction | String | да | Сериализованный в json строку объект PTTransaction полученный в результатах оплаты. |
Получение результата оплаты/возврата/отмены
Действие: ru.lifepay.checkout.payment_terminal.transaction.get_result
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| request_id | String | да | Значение request_id, которое было передано при первоначальном проведении операции. |
| metadata | HashMap<String, String> | нет | Значение metadata, которое было передано при первоначальном проведении операции. |
Сверка итогов
Действие: ru.lifepay.checkout.payment_terminal.close_shift
Параметры запроса:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| request_id | String | нет | Уникальный идентификатор запроса. Возвращается в ответе. |
| metadata | HashMap<String, String> | нет | Дополнительные пользовательские данные. Возвращаются в ответе. |
Дополнительные параметры запроса
В зависимости от действия (action) и платежного терминала в запросах могут использоваться дополнительные параметры.
Дополнительные параметры запросов для терминала Lifepay QPOS приведены далее.
Операция: Оплата
Действие: ru.lifepay.checkout.payment_terminal.transaction.pay
Дополнительные параметры запроса для терминала Lifepay QPOS:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| login | String | да | Логин пользователя в системе Lifepay. |
| password | String | да | Пароль пользователя в системе Lifepay. |
| sign_on_screen | String | нет | “1” - да, “0” - нет. По умолчанию “0”. Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью. |
| String | нет | Почта на которую будет отправлен электронный СЛИП чек оплаты. | |
| phone | String | нет | Телефон на который будет отправлено SMS с электронным СЛИП чеком оплаты. |
| recipient_inn | String | нет | ИНН получателя платежа. |
Операции: Возврат, Отмена
Действия: ru.lifepay.checkout.payment_terminal.transaction.refund, ru.lifepay.checkout.payment_terminal.transaction.cancel
Дополнительные параметры запросов для терминала Lifepay QPOS:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| login | String | да | Логин пользователя в системе Lifepay. |
| password | String | да | Пароль пользователя в системе Lifepay. |
| sign_on_screen | String | нет | “1” - да, “0” - нет. По умолчанию “0”. Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью. |
Операция: Получение результата оплаты/возврата/отмены
Действие: ru.lifepay.checkout.payment_terminal.transaction.get_result
Дополнительные параметры запроса для терминала Lifepay QPOS:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| login | String | да | Логин пользователя в системе Lifepay. |
| password | String | да | Пароль пользователя в системе Lifepay. |
Параметры результата запроса
В случае успешной обработки запроса приложение LIFE POS Checkout возвращает resultCode = Activity.RESULT_OK (-1) и экземпляр класса Intent с действием action которое было указано во входящем интенте.
Если resultCode отличается от Activity.RESULT_OK или intent == null, то следует рассматривать данную ситуацию как ошибку.
Успешная обработка запроса еще не означает, что операция (например платежная транзакция) проведена успешно.
Для определения факта успешного/неуспешного выполнения операции следует ориентироваться на значение параметра code, значение 0 соответствует успешному выполнению операции, значение отличное от 0 соответствует ошибке.
Поля результата запроса в случае успешного выполнения операции:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| code | Int | да | 0 - операция проведена успешно. |
| data | String | да | Сериализованный в json строку результат операции. Смотрите таблицу соответствия операций и моделей. |
| request_id | String | да | Значение request_id, которое было передано в запросе. Если значение не было передано в запросе, то оно генерируется автоматически. |
| metadata | HashMap<String, String> | нет | Значение metadata, которое было передано в запросе. Извлекается через extras.getSerializable(“metadata”). |
Значения полей можно извлекать из экземпляра класса Bundle получаемого из свойства extras (метод getExtras() в случае java) класса Intent при помощи методов extras.getInt(...) и extras.getString(...).
Параметры результата запроса в случае ошибки:
| Название | Тип | Обязательность | Значение/описание |
|---|---|---|---|
| code | Int | да | Отличное от нуля значение. Означает, что произошла ошибка. |
| request_id | String | да | Значение request_id, которое было передано в запросе. Если значение не было передано в запросе, то оно генерируется автоматически. |
| metadata | HashMap<String, String> | нет | Значение metadata, которое было передано в запросе. Извлекается через extras.getSerializable(“metadata”). |
| error_type | String | да | Тип ошибки. Каждый тип имеет свою собственную логику обработки. Смотрите Типы ошибок. |
| message | String | да | Текст ошибки для вывода пользователю. |
| log | String | нет | Дополнительная информация об ошибке для разработчиков. Для пользователей ее выводить не нужно. Может быть полезной на этапе интеграции и тестирования. Может иметь большой размер. |
Тип ошибки (error_type) |
Описание |
|---|---|
| default_error | Обычная ошибка. |
| unknown_result_error | Результат операции неизвестен. Выдается только для терминалов и операций поддерживающих операцию получения результата оплаты/возврата/отмены. Логику обработки смотрите в разделе Получение результата оплаты/возврата/отмены. |
| duplicate_request_error | Повторный запрос с одним и тем же request_id. Выдается только для терминалов и операций поддерживающих операцию получения результата оплаты/возврата/отмены. Логику обработки смотрите в разделе Получение результата оплаты/возврата/отмены. |
| result_not_found_error | Результат операции не найден. Выдается только на запрос получения результата оплаты/возврата/отмены. Подробнее в разделе Получение результата оплаты/возврата/отмены. |
Получение результата оплаты/возврата/отмены
Операция получения результата оплаты/возврата/отмены поддерживается некоторыми видами терминалов. Смотрите таблицу платежные терминалы и поддерживаемые операции.
Для каждого запроса в приложение LIFE POS Checkout можно передавать параметр request_id.
В случае если его не передать, то он будет сгенерирован автоматически и вернется в успешном/неуспешном ответе.
request_id является уникальным идентификатором запроса и используется локально в приложении LIFE POS Checkout для получения результата оплаты/возврата/отмены в случае необходимости.
Для этого необходимо отправить запрос в LIFE POS Checkout на получение результата оплаты/возврата/отмены. В результате выполнения этого запроса (успешного/неуспешного), выдается такой же ответ, как и в случае запросов на выполнение операций оплаты/возврата/отмены. Смотрите раздел Параметры результата запроса.
Далее приводится алгоритм обработки ошибок с типами error_type == unknown_result_error и error_type == duplicate_request_error.
Данные ошибки могут выдаваться для терминалов и операций оплаты/возврата/отмены, в случае если терминал и операция поддерживают получение результата. Смотрите таблицу платежные терминалы и поддерживаемые операции.
Если терминал или операция не поддерживают получение результата, то ошибки unknown_result_error и duplicate_request_error для них не выдаются.
Получение результата операции работает определенное ограниченное время после проведения операции. К примеру для терминала Lifepay QPOS запоминается локально 500 последних запросов, а терминал СБЕРБАНК ICMP стирает результаты операций после проведения сверки итогов.
Если в результате проведения операции происходит ошибка с
error_type == unknown_result_error, то это означает что результат операции неизвестен, он может быть как успешным, так и нет. В этом случае можно проверить результат выполнения операции, отправив запрос получения результата оплаты/возврата/отмены в LIFE POS Checkout. Не стоит отправлять этот запрос автоматически после получения ошибки, т.к. данная ошибка может произойти из-за того, что терминал потерял связь со смартфоном или сел. Рекомендуется предупредить кассира и предложить ему запросить результат операции нажав на кнопку. Пример реализации данного алгоритма смотрите в демо приложении в классеResponseHandler.Запрос получения результата оплаты/возврата/отмены также может закончиться ошибкой с типом
error_type == unknown_result_error. Например если не удалось соединиться с терминалом или отсутствует связь с интернетом. В этом случае можно повторить алгоритм из пункта 1.Если запрос получения результата оплаты/возврата/отмены заканчивается ошибкой с типом
error_type != unknown_result_error, тогда обновляемrequest_idдля проведения операции заново.Если в результате проведения операции оплаты/возврата/отмены происходит ошибка с
error_type == duplicate_request_error, то переходим к пункту 1 алгоритма. Данная ошибка возникает в случае попытки провести операцию с тем жеrequest_id, что и ранее. А это означает, что по предыдущей операции не был получен результат иrequest_idне был изменен.
Не используйте в качестве request_id какие либо внутренние глобальные идентификаторы заказа/покупки/продажи из своей системы.
Как описано выше для одной и той же операции может потребоваться изменять request_id, в процессе попыток ее проведения.
Если вам требуется передавать ваш внутренний глобальный идентификатор заказа/покупки/продажи вместе с параметрами операции смотрите раздел Передача дополнительных данных.
Передача дополнительных данных
Приложение LIFE POS Checkout позволяет передавать дополнительные данные при проведении операций. Например это может быть уникальный идентификатор заказа/покупки/продажи из вашей системы.
При использовании терминала Lifepay QPOS это дает возможность получать оповещение стороннего сервера о транзакции, если в ЛК Lifepay указан URL для уведомлений.
Для реализации этого механизма, необходимо передавать параметр metadata в параметрах запросов.
Пример заполнения параметра metadata:
kotlin
val metadata = HashMap<String, String>().apply {
put("OrderId", "12345")
}
intent.putExtra("metadata", metadata)
java
HashMap<String, String> metadata = new HashMap<>();
metadata.put("OrderId", "12345");
intent.putExtra("metadata", metadata);
Никаких проверок на дублирование для данного параметра не производится.