SDK Pay to phone 2.0
С 1 октября 2024 года SDK 1.0 не поддерживается.
Pay to phone — это Android-приложение для бизнеса со счётом в Т‑Бизнесе, которое позволяет принимать бесконтактную оплату картами или QR-кодом от покупателя при помощи смартфона. Операция бесконтактной оплаты в мобильном приложении Pay to phone поддерживается на Android-смартфонах с модулем NFC.
SDK 2.0 позволяет интегрировать приложение Pay to phone с кассовым приложением от производителя касс или товароучётным приложением, которое будет расположено в контуре одного смартфона.
Технические требования
SDK Pay to phone написан на Kotlin. Требования к устройству:
- минимальная версия ОС Android — Android 10.0 (api 29);
- уровень API Android SDK, с которым компилируется модуль — 33.
Учитывайте порядок установки приложений: сначала устанавливается Pay to phone, потом — приложение клиента (касса). Иначе
на уровне Android не будет хватать системных разрешений для вызова интеграции.
Например, при неправильном порядке установки может возникнуть ошибка Not allowed to bind to serviceintent.
Чтобы методы класса TSoftposManager работали корректно, дождитесь окончания подготовки устройства после установки Pay to phone. Для первого входа:
- Зарегистрируйте учётную запись или авторизуйтесь в существующей.
- Создайте или выберите точку приёма оплаты.
- Пройдите онбординг и перейдите на экран терминала.
Лимиты и ограничения
Ограничения передачи значений суммы оплаты или возврата:
- Не больше 11 цифр.
- Не меньше 100 копеек.
- Не больше 999 999 999 99 копеек.
Безопасность
Чтобы безопасно использовать Pay to phone, по требованиям регулятора нужно закладывать слой верификации вызывающего приложения — это нужно, чтобы исключить неизвестные вызовы.
Для этого при вызове Pay to phone нужно передать название пакета приложения и SHA-256 хэш сертификата.
Чтобы получить SHA-256 хэш сертификата с помощью команд Gradle:
- Откройте терминал или командную строку и перейдите в папку с проектом мобильного приложения.
- Выполните команду для получения SHA-256 хэша:
./gradlew signingReport
Дождитесь выполнения команды. Gradle будет выполнять скрипт, чтобы найти все сертификаты и вывести информацию о них, включая SHA-256 хэш.
- После выполнения команды результат отобразится в терминале. Найдите раздел с ключевыми характеристиками каждого сертификата, где будет указан SHA-256 хэш. Обычно он выглядит так:
SHA256: EA:7F:AB:5A:C2:8C:3F:1F:8E:4E:41:12:EE:47:C0:BF:91:27:87:6F:59:FC:88:F0:60:52:EC:1C:8B:01:E2
- Направьте SHA-256 хэш и название пакета приложения команде разработки Pay to phone на pay2phone@tbank.ru.
Все данные будут храниться в коде приложения и защищаться такими же методами криптографии, как и остальная часть приложения.
Сейчас SDK предоставляется по запросу на pay2phone@tbank.ru — мы высылаем его после того, как получим ваши хэш сертификата и название пакета приложения.
Оплата
Приложение клиента → Pay to phone SDK → Pay to phone.
Весь цикл вызова происходит в Pay to phone SDK через методы класса TSoftPosManager.
Входные параметры
Для проведения оплаты используется метод payToPhone:
| Да | Содержит входную информацию для совершения возврата средств. | |||
| Да | Значение суммы возврата, соответствует значению в копейках. | |||
| Нет | Способ оплаты. Возможные значения — NFC/QR Если значение параметра не передано, ему присваивается значение UNDEFINED. | |||
| Да | Интерфейс для получения ответа. | |||
Выходные параметры
Для передачи информации о результате оплаты используется интерфейс Callback. Методы:
- onTransactionRegistered — при успешной оплате;
- onError — при неуспешной оплате.
onTransactionRegistered
| Содержит итоговую информацию о возврате средств. | |||
Сумма возврата, соответствует значению в копейках. Повторяет значение amount из входных параметров. | |||
Способ оплаты — NFC/QR. | |||
Идентификатор операции, соответствует rrn/sbpRrn. | |||
| Тип операции — оплата или возврат. | |||
Дата и время проведения транзакции. Значение передаётся в часовом поясе устройства в формате yyyy-MM-dd'T'HH:mm:ssXXX, согласно стандарту ISO 8601. | |||
| Идентификатор терминала. | |||
| Идентификатор торговой точки. | |||
onError
| Object | Содержит информацию об ошибке. | ||
| code | Внутренний код ошибки. | ||
| details | Текстовая интерпретация ошибки. | ||
Возврат средств
Приложение клиента → Pay to phone SDK → Pay to phone.
Весь цикл вызова происходит в Pay to phone SDK через методы класса TSoftPosManager.
Входные параметры
Для проведения возврата средств используется метод payToPhone:
| Да | Содержит входную информацию для совершения возврата средств. | |||
| Long | Да | Значение суммы возврата, соответствует значению в копейках. | ||
| Enum | Да | Способ оплаты. Возможные значения — NFC/QR. | ||
| Long | Да | Идентификатор платежа, соответствует rrn/sbpRrn. | ||
| Long | Да | Идентификатор торговой точки. | ||
| Да | Интерфейс для получения ответа. | |||
Выходные параметры
Для передачи информации о результате возврата средств используется интерфейс Callback. Методы:
- onTransactionRegistered — при успешном возврате;
- onError — при неуспешном возврате.
onTransactionRegistered
| Параметр | Описание | ||
|---|---|---|---|
| Содержит итоговую информацию о возврате средств. | |||
Сумма возврата, соответствует значению в копейках. Повторяет значение amount из входных параметров. | |||
Способ оплаты — NFC/QR. | |||
Идентификатор операции, соответствует rrn/sbpRrn. | |||
| Тип операции — оплата или возврат. | |||
Дата и время проведения транзакции. Значение передаётся в часовом поясе устройства в формате yyyy-MM-dd'T'HH:mm:ssXXX, согласно стандарту ISO 8601. | |||
| Идентификатор терминала. | |||
| Идентификатор торговой точки. | |||
onError
| Параметр | Тип | Значение | |
|---|---|---|---|
| SoftposException | Object | Содержит информацию об ошибке. | |
| code | Int | Внутренний код ошибки. | |
| details | String | Текстовая интерпретация ошибки. | |
Коды ошибок
| Покупатель отменил операцию. | Отменено по инициативе пользователя. | |
| Лимит на сумму операции — значение оплаты выше или ниже допустимого. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | Валидация значений аргументов. | |
| Только для возвратов. Не получилось вернуть деньги в этой точке. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | ||
| Прием платежей заблокирован. Нет сертификата. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | Валидация сертификата. | |
| Прием платежей заблокирован — сертификат не прошел проверку. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | ||
| Прием платежей заблокирован — не получилось проверить сертификат. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | ||
| Нет доступа. Чтобы узнать детали, обратитесь в поддержку вызывающего приложения. | Недостаточно прав на стороне вызывающего приложения. | |
| Текст из UI мобильного приложения с описанием обнаруженной ошибки. | Ошибки от бэкенда, ответственного за операции по карте, при оплате или возврате. | |
| Текст из UI мобильного приложения с описанием обнаруженной ошибки. | Ошибки от бэкенда, ответственного за операции по QR-коду, при оплате или возврате. |
Pay to phone mock
Pay to phone mock — отдельное приложение для тестирования и отладки интеграции с Pay to phone SDK. С его помощью можно проводить тестовые операции с заранее определенным результатом.
Для работы с приложением не нужно регистрировать какие-либо данные в продуктовом контуре — всё уже учтено и предустановлено.
Технические требования
Требования к устройству для Pay to phone mock те же, что и для Pay to phone SDK.
Авторизация
| На этапе ввода номера телефона достаточно ввести любой номер телефона, который удовлетворяет валидации. | |
| После ввода номера системой будет предложен ввод одноразового кода — достаточно ввести любую четырехзначную последовательность. | |
| На этапе ввода кода нужно дважды указать код, который удовлетворяет валидации. | |
| После ввода кода будет предложено дать доступ к биометрии, чтобы упростить авторизацию в приложении. |
Загрузка данных терминала
Заключительный этап — выбор торговой точки. Данные загружаются автоматически после выбора компании или ИП и торговой точки — достаточно выбрать любые данные из предложенных.
Режим работы терминала
После загрузки всех необходимых данных терминал будет готов для проведения тестовых операций. По умолчанию для всех типов операций предопределен успешный результат.
Настройка режима
Результат регулируется через управление переключателем, который расположен в debug-панели приложения. Через нее можно регулировать результат одновременно для обоих типов операций — оплаты и возврата.
Для доступа к debug-панели и настройкам:
- Авторизуйтесь.
- Трижды нажмите в верхней части приложения на любом из экранов.
- Переведите переключатель в нужное положение, где включен — это успешный исход, а выключен — ошибка.
- Перезайдите в приложение.