Платежный терминал

Модуль 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”. Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью.
email 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 стирает результаты операций после проведения сверки итогов.

  1. Если в результате проведения операции происходит ошибка с error_type == unknown_result_error, то это означает что результат операции неизвестен, он может быть как успешным, так и нет. В этом случае можно проверить результат выполнения операции, отправив запрос получения результата оплаты/возврата/отмены в LIFE POS Checkout. Не стоит отправлять этот запрос автоматически после получения ошибки, т.к. данная ошибка может произойти из-за того, что терминал потерял связь со смартфоном или сел. Рекомендуется предупредить кассира и предложить ему запросить результат операции нажав на кнопку. Пример реализации данного алгоритма смотрите в демо приложении в классе ResponseHandler.

  2. Запрос получения результата оплаты/возврата/отмены также может закончиться ошибкой с типом error_type == unknown_result_error. Например если не удалось соединиться с терминалом или отсутствует связь с интернетом. В этом случае можно повторить алгоритм из пункта 1.

  3. Если запрос получения результата оплаты/возврата/отмены заканчивается ошибкой с типом error_type != unknown_result_error, тогда обновляем request_id для проведения операции заново.

  4. Если в результате проведения операции оплаты/возврата/отмены происходит ошибка с 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);

Никаких проверок на дублирование для данного параметра не производится.