Операции платёжного терминала

Общая информация

LIFE POS Checkout может принимать оплату по банковской карте через платежный терминал, например через QPOS mini. Для этого модуль periphery-models, подключаемый через build.gradle, содержит набор классов результатов выполнения операций через платежный терминал.

Для каждого действия action используется своя модель результата операции, смотрите таблицу соответствия операций и моделей.

Модели передаются и получаются в виде json строки, которая является сериализованным представлением модели. Чтобы сериализовать модель в json строку используйте метод toJSON().

Для десериализации json строки в соответствующую модель используйте метод fromJSON() с указанием нужного класса модели:

Kotlin
Java

GSONConverter.fromJSON(data, FDReceipt::class.java)

GSONConverter.fromJSON(data, FDReceipt.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

Оплата

Действие: ru.lifepay.checkout.payment_terminal.transaction.pay

Параметры входящего запроса

Название	Тип	Обязательность	Значение/описание
request_id	String	нет	Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата оплаты по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены.
metadata	HashMap<String, String>	нет	Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных.
amount	Long	да	Сумма оплаты в копейках.

Дополнительные параметры

Название	Тип	Обязательность	Значение/описание
login	String	да	Логин пользователя в системе Lifepay.
password	String	да	Пароль пользователя в системе Lifepay.
sign_on_screen	String	нет	"1" - да, "0" - нет. По умолчанию "0". Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью.
email	String	нет	Почта на которую будет отправлен электронный СЛИП чек оплаты.
phone	String	нет	Телефон на который будет отправлено SMS с электронным СЛИП чеком оплаты.
recipient_inn	String	нет	ИНН получателя платежа.

Пример выполнения запроса

Пример выполнения запроса на Kotlin:

fun pay(
    requestId: String,
    metadata: HashMap\<String, String>?,
    amount: Long
) {
    val lifepaySpecificData = LifepaySpecificDataRepository.getData()
    sendRequest(
        intent = Intent(Actions.ru.lifepay.checkout.payment_terminal.transaction.pay)
            .putExtra("request_id", requestId)
            .putExtra("metadata", metadata)
            .putExtra("amount", amount)

            .apply {
                putExtra("sign_on_screen", if (lifepaySpecificData.signOnScreen) "1" else "0")
                if (!lifepaySpecificData.login.isNullOrEmpty()) {
                    putExtra("login", lifepaySpecificData.login)
                }
                if (!lifepaySpecificData.password.isNullOrEmpty()) {
                    putExtra("password", lifepaySpecificData.password)
                }
                if (!lifepaySpecificData.email.isNullOrEmpty()) {
                    putExtra("email", lifepaySpecificData.email)
                }
                if (!lifepaySpecificData.phone.isNullOrEmpty()) {
                    putExtra("phone", lifepaySpecificData.phone)
                }
                if (!lifepaySpecificData.recipientInn.isNullOrEmpty()) {
                    putExtra("recipient_inn", lifepaySpecificData.recipientInn)
                }
            }
    )
}

Возврат

Действие: ru.lifepay.checkout.payment_terminal.transaction.refund

Параметры входящего запроса

Название	Тип	Обязательность	Значение/описание
request_id	String	нет	Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата возврата по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены.
metadata	HashMap<String, String>	нет	Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных.
amount	Long	да	Сумма возврата в копейках.
primary_transaction	String	да	Сериализованный в json строку объект PTTransaction полученный в результатах оплаты.

Дополнительные параметры

Название	Тип	Обязательность	Значение/описание
login	String	да	Логин пользователя в системе Lifepay.
password	String	да	Пароль пользователя в системе Lifepay.
sign_on_screen	String	нет	"1" - да, "0" - нет. По умолчанию "0". Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью.

Пример выполнения запроса

Пример выполнения запроса на Kotlin:

fun refund(
    requestId: String,
    amount: Long,
    primaryTransaction: PTTransaction
) {
    val lifepaySpecificData = LifepaySpecificDataRepository.getData()
    sendRequest(
        intent = Intent(Actions.ru.lifepay.checkout.payment_terminal.transaction.refund)
            .putExtra("request_id", requestId)
            .putExtra("amount", amount)
            .putExtra("primary_transaction", primaryTransaction.toJSON())

            .apply {
                putExtra("sign_on_screen", if (lifepaySpecificData.signOnScreen) "1" else "0")
                if (!lifepaySpecificData.login.isNullOrEmpty()) {
                    putExtra("login", lifepaySpecificData.login)
                }
                if (!lifepaySpecificData.password.isNullOrEmpty()) {
                    putExtra("password", lifepaySpecificData.password)
                }
            }
    )
}

Отмена

Действие: ru.lifepay.checkout.payment_terminal.transaction.cancel

Параметры входящего запроса

Название	Тип	Обязательность	Значение/описание
request_id	String	нет	Уникальный идентификатор запроса. Возвращается в ответе. Некоторые виды терминалов поддерживают операцию получения результата отмены по request_id. Логику работы смотрите в разделе Получение результата оплаты/возврата/отмены.
metadata	HashMap<String, String>	нет	Дополнительные пользовательские данные. Возвращаются в ответе. Смотрите раздел Передача дополнительных данных
amount	Long	да	Сумма отмены в копейках.
primary_transaction	String	да	Сериализованный в json строку объект PTTransaction полученный в результатах оплаты.

Дополнительные параметры

Название	Тип	Обязательность	Значение/описание
login	String	да	Логин пользователя в системе Lifepay.
password	String	да	Пароль пользователя в системе Lifepay.
sign_on_screen	String	нет	"1" - да, "0" - нет. По умолчанию "0". Необходимо ли выводить экран для ввода подписи покупателя на смартфоне в случае необходимости подтвердить транзакцию подписью.

Пример выполнения запроса

Пример выполнения запроса на Kotlin:

fun cancel(
    requestId: String,
    amount: Long,
    primaryTransaction: PTTransaction
) {
    val lifepaySpecificData = LifepaySpecificDataRepository.getData()
    sendRequest(
        intent = Intent(Actions.ru.lifepay.checkout.payment_terminal.transaction.cancel)
            .putExtra("request_id", requestId)
            .putExtra("amount", amount)
            .putExtra("primary_transaction", primaryTransaction.toJSON())

            .apply {
                putExtra("sign_on_screen", if (lifepaySpecificData.signOnScreen) "1" else "0")
                if (!lifepaySpecificData.login.isNullOrEmpty()) {
                    putExtra("login", lifepaySpecificData.login)
                }
                if (!lifepaySpecificData.password.isNullOrEmpty()) {
                    putExtra("password", lifepaySpecificData.password)
                }
            }
    )
}

Получение результата оплаты/возврата/отмены

Действие: ru.lifepay.checkout.payment_terminal.transaction.get_result

Параметры входящего запроса

Название	Тип	Обязательность	Значение/описание
request_id	String	да	Значение request_id, которое было передано при первоначальном проведении операции.
metadata	HashMap<String, String>	нет	Значение metadata, которое было передано при первоначальном проведении операции.

Дополнительные параметры

Название	Тип	Обязательность	Значение/описание
login	String	да	Логин пользователя в системе Lifepay.
password	String	да	Пароль пользователя в системе Lifepay.

Пример выполнения запроса

Пример выполнения запроса на Kotlin:

fun getResult(
    requestId: String,
    metadata: Serializable?
) {
    val lifepaySpecificData = LifepaySpecificDataRepository.getData()
    sendRequest(
        intent = Intent(Actions.ru.lifepay.checkout.payment_terminal.transaction.get_result)
            .putExtra("request_id", requestId)
            .putExtra("metadata", metadata)

            .apply {
                if (!lifepaySpecificData.login.isNullOrEmpty()) {
                    putExtra("login", lifepaySpecificData.login)
                }
                if (!lifepaySpecificData.password.isNullOrEmpty()) {
                    putExtra("password", lifepaySpecificData.password)
                }
            }
    )
}

Сверка итогов

Действие: ru.lifepay.checkout.payment_terminal.close_shift

Параметры входящего запроса

Название	Тип	Обязательность	Значение/описание
request_id	String	нет	Уникальный идентификатор запроса. Возвращается в ответе.
metadata	HashMap<String, String>	нет	Дополнительные пользовательские данные. Возвращаются в ответе.

Пример выполнения запроса

Пример выполнения запроса на Kotlin:

fun closeShift() {
    sendRequest(Intent(Actions.ru.lifepay.checkout.payment_terminal.close_shift))
}

private fun sendRequest(intent: Intent) {
    Logger.logRequest(intent)
    try {
        activity.startActivityForResult(intent, 5555) //число 5555 взято просто так, можно использовать другое число.
    } catch (e: ActivityNotFoundException) {
        errorCallback.invoke("Приложение LIFE POS Checkout не установлено на устройстве. Необходимо установить приложение.")
    } catch (e: Throwable) {
        errorCallback.invoke(e.message)
    }
}

Параметры результата запроса

При успешном запросе Checkout возвращает resultCode = Activity.RESULT_OK (-1) и экземпляр класса Intent с действием action, которое было указано во входящем интенте.

При ошибке Checkout вернёт 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 класса 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	да	Текст ошибки для вывода пользователю.

Типы ошибок

Тип ошибки (`error_type`)	Описание
default_error	Обычная ошибка.
unknown_result_error	Результат операции неизвестен. Выдается только для терминалов и операций поддерживающих операцию получения результата оплаты/возврата/отмены. Логику обработки смотрите в разделе Получение результата оплаты/возврата/отмены.
duplicate_request_error	Повторный запрос с одним и тем же request_id. Выдается только для терминалов и операций поддерживающих операцию получения результата оплаты/возврата/отмены. Логику обработки смотрите в разделе Получение результата оплаты/возврата/отмены.
result_not_found_error	Результат операции не найден. Выдается только на запрос получения результата оплаты/возврата/отмены. Подробнее в разделе Получение результата оплаты/возврата/отмены.

Получение результата оплаты, возврата, отмены

Для каждого запроса в Checkout можно передавать параметр request_id. В случае если его не передать, то он будет сгенерирован автоматически и вернется в ответе.

request_id это уникальный идентификатор запроса в приложении LIFE POS Checkout для получения результата операции при необходимости. Для этого отправьте запрос в Checkout на получение результата оплаты/возврата/отмены. В результате выполнения вы получите такой же ответ, как и в запросе на выполнение операций оплаты/возврата/отмены. Смотрите раздел Параметры результата запроса.

Для терминалов и операций оплаты, возврата, отмены в параметре ошибки error_type могут возвращаться значения unknown_result_error и duplicate_request_error. Их поддерживают не все терминалы и типы операций. Смотрите таблицу платежные терминалы и поддерживаемые операции. Если терминал или операция не поддерживают получение результата, то эти ошибки не возвращаются.

Получение результата операции доступно ограниченное время после проведения операции. Например, LIFE PAY QPOS запоминает 500 последних запросов.

Алгоритм обработки ошибок unknown_result_error и duplicate_request_error

Если в результате проведения операции происходит ошибка unknown_result_error, то результат операции неизвестен. Он может быть как успешным, так и неуспешным. В этом случае можно проверьте результат операции, отправив запрос получения результата оплаты/возврата/отмены в LIFE POS Checkout.

info

Не отправляйте этот запрос автоматически после получения ошибки. Эта ошибка может произойти из-за того, что терминал потерял связь со смартфоном или сел.

Мы рекомендуем предупредить кассира и предложить ему запросить результат операции нажатием на кнопку. Пример такой реализации смотрите в демонстрационном приложении в классе ResponseHandler.

Запрос получения результата оплаты/возврата/отмены также может закончиться ошибкой с типом unknown_result_error. Например, если не удалось соединиться с терминалом или отсутствует связь с интернетом. В этом случае можно повторите алгоритм из пункта 1.
Если запрос получения результата оплаты/возврата/отмены заканчивается ошибкой с типом отличным от unknown_result_error, тогда обновите request_id для проведения операции заново.
Если в результате проведения операции оплаты/возврата/отмены происходит ошибка с duplicate_request_error, то повторите пункт 1 алгоритма. Эта ошибка возникает при попытке провести операцию с тем же request_id, что и ранее. А значит, что по предыдущей операции не был получен результат и request_id не был изменен.

info

Не используйте в качестве request_id какие-либо внутренние глобальные идентификаторы заказа/покупки/продажи из своего приложения. Для одной и той же операции может потребоваться изменять request_id в процессе попыток ее проведения.

Если вам требуется передавать ваш внутренний идентификатор заказа/покупки/продажи вместе с параметрами операции смотрите раздел Передача дополнительных данных.

Передача дополнительных данных

LIFE POS Checkout позволяет передавать дополнительные данные при проведении операций. Например, уникальный идентификатор заказа из вашего приложения.

При использовании Lifepay QPOS это даёт возможность получать оповещение стороннего сервера о транзакции, если в ЛК Lifepay указан URL для уведомлений.

Для передачи дополнительных параметров используйте metadata в параметрах запросов. Никаких проверок на дублирование для этого параметра не выполняется. Пример заполнения параметра metadata:

Kotlin
Java

val metadata = HashMap\<String, String>().apply {
            put("OrderId", "12345")
        }
intent.putExtra("metadata", metadata)

HashMap<String, String> metadata = new HashMap<>();
metadata.put("OrderId", "12345");
intent.putExtra("metadata", metadata);

Общая информация​

Соответствие операций и моделей​

Поддерживаемые платежные терминалы и операции​

Оплата​

Параметры входящего запроса​

Дополнительные параметры​

Пример выполнения запроса​

Возврат​

Параметры входящего запроса​

Дополнительные параметры​

Пример выполнения запроса​

Отмена​

Параметры входящего запроса​

Дополнительные параметры​

Пример выполнения запроса​

Получение результата оплаты/возврата/отмены ​

Параметры входящего запроса​

Дополнительные параметры​

Пример выполнения запроса​

Сверка итогов​

Параметры входящего запроса​

Пример выполнения запроса​

Параметры результата запроса​

Параметры результата при успешном выполнении операции​

Параметры результата при ошибке​

Типы ошибок​

Получение результата оплаты, возврата, отмены​

Передача дополнительных данных​

Общая информация

Соответствие операций и моделей

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

Оплата

Параметры входящего запроса

Дополнительные параметры

Пример выполнения запроса

Возврат

Параметры входящего запроса

Дополнительные параметры

Пример выполнения запроса

Отмена

Параметры входящего запроса

Дополнительные параметры

Пример выполнения запроса

Получение результата оплаты/возврата/отмены

Параметры входящего запроса

Дополнительные параметры

Пример выполнения запроса

Сверка итогов

Параметры входящего запроса

Пример выполнения запроса

Параметры результата запроса

Параметры результата при успешном выполнении операции

Параметры результата при ошибке

Типы ошибок

Получение результата оплаты, возврата, отмены

Передача дополнительных данных