SDK Pay to phone 2.0

Pay to phone

С 1 октября 2024 года SDK 1.0 не поддерживается.

Pay to phone — это Android-приложение для бизнеса со счетом в Т‑Бизнесе, которое позволяет принимать бесконтактную оплату картами или QR-кодом от покупателя при помощи смартфона. Операция бесконтактной оплаты в мобильном приложении Pay to phone поддерживается на Android-смартфонах с модулем NFC.

SDK 2.0 позволяет интегрировать приложение Pay to phone с кассовым приложением от производителя касс или товароучетным приложением, которое будет расположено в контуре одного смартфона.

Подробнее о Pay to phone

Установка SDK Pay to phone

Если вы хотите протестировать интеграцию с Pay to phone SDK, используйте Pay to phone mock — через него можно проводить тестовые операции с нужным вам результатом.

Технические требования

SDK Pay to phone написан на Kotlin. Требования к устройству:

минимальная версия ОС Android — Android 10.0 (api 29);
уровень API Android SDK, с которым компилируется модуль — 33;
есть модуль NFC;
не подключены root-права.

Чтобы методы класса TSoftposManager работали корректно, дождитесь окончания подготовки устройства после установки Pay to phone. Для первого входа:

Зарегистрируйте учетную запись или авторизуйтесь в существующей.
Создайте или выберите точку приема оплаты.
Пройдите онбординг и перейдите на экран терминала.

Лимиты и ограничения

Ограничения передачи значений суммы оплаты или возврата:

Не больше 11 цифр.
Не меньше 100 копеек.
Не больше 999 999 999 99 копеек.

Безопасность

Чтобы безопасно вызывать мобильное приложение Pay to phone через SDK Pay to phone, нужно закладывать слой верификации вызывающего приложения — это требования регулятора и делается для того, чтобы исключить неизвестные вызовы.

При интеграции через SDK Pay to phone с приложением:

Pay to phone mock — валидации нет.
Pay to phone — мы проверяем название пакета приложения и SHA-256 хэш сертификата.

Все данные будут храниться в коде приложения и защищаться такими же методами криптографии, как и остальная часть приложения.

Если вы интегрируетесь с мобильным приложением Pay to phone с разных сборок, у которых разные packageName или хэш — например, тестовой, дебажной и продовой — предоставьте данные всех версий.
Используйте постоянный релизный key-store и подписывайте все сборки с его помощью. Если передан правильный хэш, значение Alias в отчете не будет равно AndroidDebugKey.

Оплата

Приложение клиента → Pay to phone SDK → Pay to phone.

Весь цикл вызова происходит в Pay to phone SDK через методы класса TSoftPosManager.

Входные параметры

Для проведения оплаты используется метод payToPhone:

Параметр		Тип	Обязательность	Описание
PaymentTransactionData		Object	Да	Содержит входную информацию для совершения возврата средств.
	amount	Long	Да	Значение суммы возврата, соответствует значению в копейках.
	paymentMethod	Enum	Нет	Способ оплаты. Возможные значения — `NFC`/`QR` Если значение параметра не передано, ему присваивается значение `UNDEFINED`.
Callback		Object	Да	Интерфейс для получения ответа.

Выходные параметры

Для передачи информации о результате оплаты используется интерфейс Callback. Методы:

onTransactionRegistered — при успешной оплате;
onError — при неуспешной оплате.

onTransactionRegistered

Параметр		Тип	Описание
SoftposResult		Object	Содержит итоговую информацию о возврате средств.
	amount	Long	Сумма возврата, соответствует значению в копейках. Повторяет значение `amount` из входных параметров.
	paymentMethod	Enum	Способ оплаты — `NFC`/`QR`.
	transactionId	Long	Идентификатор операции, соответствует `rrn`/`sbpRrn`.
	isRefund	Bool	Тип операции — оплата или возврат.
	dateTime	String	Дата и время проведения транзакции. Значение передается в часовом поясе устройства в формате `yyyy-MM-dd'T'HH:mm:ssXXX`, согласно стандарту ISO 8601.
	tid	Long	Идентификатор терминала.
	mid	Long	Идентификатор торговой точки.

onError

Параметр		Тип	Значение
SoftposException		Object	Содержит информацию об ошибке.
	code	Int	Внутренний код ошибки.
	details	String	Текстовая интерпретация ошибки.

Возврат средств

Приложение клиента → Pay to phone SDK → Pay to phone.

Весь цикл вызова происходит в Pay to phone SDK через методы класса TSoftPosManager.

Входные параметры

Для проведения возврата средств используется метод payToPhone:

Параметр		Тип	Обязательность	Описание
RefundTransactionData		Object	Да	Содержит входную информацию для совершения возврата средств.
	amount	Long	Да	Значение суммы возврата, соответствует значению в копейках.
	paymentMethod	Enum	Да	Способ оплаты. Возможные значения — `NFC`/`QR`.
	transactionId	Long	Да	Идентификатор платежа, соответствует `rrn`/`sbpRrn`.
	mid	Long	Да	Идентификатор торговой точки.
Callback		Object	Да	Интерфейс для получения ответа.

Выходные параметры

Для передачи информации о результате возврата средств используется интерфейс Callback. Методы:

onTransactionRegistered — при успешном возврате;
onError — при неуспешном возврате.

onTransactionRegistered

Параметр		Тип	Описание
SoftposResult		Object	Содержит итоговую информацию о возврате средств.
	amount	Long	Сумма возврата, соответствует значению в копейках. Повторяет значение `amount` из входных параметров.
	paymentMethod	Enum	Способ оплаты — `NFC`/`QR`.
	transactionId	Long	Идентификатор операции, соответствует `rrn`/`sbpRrn`.
	isRefund	Bool	Тип операции — оплата или возврат.
	dateTime	String	Дата и время проведения транзакции. Значение передается в часовом поясе устройства в формате `yyyy-MM-dd'T'HH:mm:ssXXX`, согласно стандарту ISO 8601.
	tid	Long	Идентификатор терминала.
	mid	Long	Идентификатор торговой точки.

onError

Параметр		Тип	Значение
SoftposException		Object	Содержит информацию об ошибке.
	code	Int	Внутренний код ошибки.
	details	String	Текстовая интерпретация ошибки.

Коды ошибок

Код	Описание ошибки	Группа
1001	Покупатель отменил операцию.	Отменено по инициативе пользователя.
2001	Лимит на сумму операции — значение оплаты выше или ниже допустимого. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.	Валидация значений аргументов.
2002	Только для возвратов. Не получилось вернуть деньги в этой точке. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.	Валидация значений аргументов.
3001	Прием платежей заблокирован. Нет сертификата. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.	Валидация сертификата.
3002	Прием платежей заблокирован — сертификат не прошел проверку. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.
3003	Прием платежей заблокирован — не получилось проверить сертификат. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.
4001	Нет доступа. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения.	Недостаточно прав на стороне вызывающего приложения.
5001	Текст из UI мобильного приложения с описанием обнаруженной ошибки.	Ошибки от бэкенда, ответственного за операции по карте, при оплате или возврате.
6001	Текст из UI мобильного приложения с описанием обнаруженной ошибки.	Ошибки от бэкенда, ответственного за операции по QR-коду, при оплате или возврате.

Pay to phone mock

Pay to phone mock — отдельное приложение для тестирования и отладки интеграции с Pay to phone SDK. С его помощью можно проводить тестовые операции с заранее определенным результатом.

Для работы с приложением не нужно регистрировать данные в продуктовом контуре — всё уже учтено и предустановлено.

Скачать Pay to phone mock

Технические требования

Требования к устройству для Pay to phone mock те же, что и для Pay to phone SDK.

Авторизация

Номер телефона	На этапе ввода номера телефона достаточно ввести любой номер телефона, который удовлетворяет валидации.
Одноразовый код	После ввода номера системой будет предложен ввод одноразового кода — достаточно ввести любую четырехзначную последовательность.
Код для входа	На этапе ввода кода нужно дважды указать код, который удовлетворяет валидации.
Биометрия	После ввода кода будет предложено дать доступ к биометрии, чтобы упростить авторизацию в приложении.

Загрузка данных терминала

Заключительный этап — выбор торговой точки. Данные загружаются автоматически после выбора компании или ИП и торговой точки — достаточно выбрать любые данные из предложенных.

Режим работы терминала

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

Настройка режима

Результат регулируется через управление переключателем, который расположен в debug-панели приложения. Через нее можно регулировать результат одновременно для обоих типов операций — оплаты и возврата.

Для доступа к debug-панели и настройкам:

Авторизуйтесь.
Трижды нажмите в верхней части приложения на любом из экранов.
Переведите переключатель в нужное положение, где включен — это успешный исход, а выключен — ошибка.
Перезайдите в приложение.