SDK Pay to phone 2.0

С 20 сентября 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 не будет хватать системных разрешений для вызова интеграции.

Чтобы методы класса 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.

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

Оплата

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

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

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

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

Параметр		Тип	Обязательность	Описание
PaymentTransactionData		Object	Да	Содержит входную информацию для совершения возврата средств.
	amount	Long	Да	Значение суммы возврата, соответствует значению в копейках.
	paymentMethod	Enum	Нет	Способ оплаты. Возможные значения — `NFC`/`QR` Если значение параметра не передано, ему присваивается значение `UNDEFINED`.
Callback		Object	Да	Интерфейс для получения ответа.
Context		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	Да	Интерфейс для получения ответа.
Context		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, поэтому тексты могут меняться в каждом релизе приложения независимо от релиза Pay to phone SDK 2.0.

№	Код	Описание ошибки	Группа
1	1001	Описание в разработке.	Пользовательский reject.
2	2001	Описание в разработке.	Валидация значений аргументов.
3	3001	Описание в разработке.	Валидация сертификата.
4	3002	Описание в разработке.
5	3003	Описание в разработке.
6	4001	Описание в разработке.	Недостаточно прав на стороне вызывающего приложения.
7	5001	Описание в разработке.	Ошибки от бэкенда, ответственного за операции по карте при оплате или возврате.
8	6001	Описание в разработке.	Ошибки от бэкенда, ответственного за операции по QR-коду при оплате или возврате.