СБП

Модуль periphery-models подключаемый через build.gradle содержит набор классов (моделей) результатов выполнения операций через СБП.

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

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

kotlin

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

java

GSONConverter.fromJSON(data, QPTransaction.class);

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

Оплата

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

Каждый запрос создает новую ссылку (QR-код) на оплату.

Параметры запроса:

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

Возврат

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

Параметры запроса:

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

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

В случае успешной обработки запроса приложение LIFE POS Checkout возвращает resultCode = Activity.RESULT_OK (-1) и экземпляр класса Intent с действием action которое было указано во входящем интенте. Если resultCode отличается от Activity.RESULT_OK или intent == null, то следует рассматривать данную ситуацию как ошибку.

Успешная обработка запроса еще не означает, что операция (оплата/возврат) проведена успешно. Для определения факта успешного/неуспешного выполнения операции следует ориентироваться на значение параметра code, значение 0 соответствует успешному выполнению операции, значение отличное от 0 соответствует ошибке.

Поля результата запроса в случае успешного выполнения операции:

Название	Тип	Обязательность	Значение/описание
code	Int	да	0 - операция проведена успешно.
transaction	String	да	Сериализованный в json строку объект QPTransaction.
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	да	Текст ошибки для вывода пользователю.

Типы ошибок:

Тип ошибки (error_type)	Описание
default_error	Обычная ошибка.
unknown_result_error	Результат операции неизвестен. Может выдаваться только для операции возврата. Логику работы смотрите в разделе Обработка ошибок возврата.

Обработка ошибок возврата

Т.к. взаимодействие с сервером СБП осуществляется по сети интернет, то при осуществлении операции возврат могут возникать ситуации, когда операция была успешно проведена, но до клиентского приложения данная информация не дошла в связи с потерей интернет соединения на долгом временном интервале. В этом случае приложение LIFE POS Checkout вернет ошибку неизвестного результата, то есть ошибку с типом error_type == unknown_result_error. В этом случае необходимо повторить операцию возврата, передав то же значение параметра request_id, которое было передано в первоначальной операции. В этом случае приложение LIFE POS Checkout не будет создавать новую операцию возврата, а получит результат первоначальной операции.

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

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

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

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

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

Для реализации этого механизма, необходимо передавать параметр 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);

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