Tinkoff Acquiring SDK for Android

Внимание! Появилась новая версия Acquiring SDK 2.0, которая теперь находится в репозитории AcquiringSdkAndroid

Рекомендуем перейти на новую версию библиотеки.

В версии 2.0 появились новые возможности:

• поддержка оплаты через Систему быстрых платежей
• поддержка тёмной темы
• возможность оплаты через Google Pay без открытия экрана SDK
• возможность добавления собственной локализации форм
• новый современный дизайн экранов

Кроме этого, теперь библиотека написана на Kotlin, а также улучшен и переработан API библиотеки.

Acquiring SDK позволяет интегрировать Интернет-Эквайринг Tinkoff в мобильные приложения для платформы Android.

Возможности SDK:

• Прием платежей (в том числе рекуррентных)
• Сохранение банковских карт клиента
• Сканирование и распознавание карт с помощью камеры или NFC
• Получение информации о клиенте и сохраненных картах
• Управление сохраненными картами
• Поддержка английского
• Поддержка Google Pay

Требования

Для работы Tinkoff Acquiring SDK необходим Android версии 4.4 и выше (API level 19).

Подключение

Для подключения SDK добавьте в build.gradle вашего проекта следующую зависимость:

compile 'ru.tinkoff.acquiring:ui:$latestVersion'

Если вы хотите внедрить сканирование с помощью библиотеки Card-IO, то необходимо добавить в build.gradle

compile 'ru.tinkoff.acquiring:card-io:$latestVersion'

Подготовка к работе

Для начала работы с SDK вам понадобятся:

• Terminal key
• Пароль
• Public key

Которые выдаются после подключения к Интернет-Эквайрингу.

Пример работы

Для проведения оплаты необходимо запустить PayFormActivity. Активити должна быть настроена на обработку конкретного платежа, поэтому для получения интента для ее запуска необходимо вызвать цепочку из методов PayFormActivity#init, PayFormStarter#prepare и PayFormStarter#setCustomerKey:

PayFormActivity
        .init("TERMINAL_KEY", "PASSWORD", "PUBLIC_KEY") // данные продавца
        .prepare(
               "ORDER-ID",                  // ID заказа в вашей системе
                1000,                       // сумма для оплаты
                "НАЗВАНИЕ ПЛАТЕЖА",         // название платежа, видимое пользователю
                "ОПИСАНИЕ ПЛАТЕЖА",         // описание платежа, видимое пользователю
                "CARD-ID",                  // ID карточки
                "[email protected]",         // E-mail клиента для отправки уведомления об оплате
                false,                      // флаг определяющий является ли платеж рекуррентным [1]
                true                        // флаг использования безопасной клавиатуры [2]
        )
        .setCustomerKey("CUSTOMER_KEY")     // уникальный ID пользователя для сохранения данных его карты
        .startActivityForResult(this, REQUEST_CODE_PAYMENT);

Можно передать данные чека на форму, указав парметр Receipt в метод PayFormStarter#setReceipt и кастомизировать форму передав мапу с параметрами в метод PayFormStarter#setData. Так же можно указать тему и запустить форму для оплаты уже с привязанных карт (реккурентынй платеж), а также указать модуль для сканирования (свой или CameraCardIOScanner)

PayFormActivity
        .init("TERMINAL_KEY", "PASSWORD", "PUBLIC_KEY") // данные продавца
        .prepare(//TODO params)
        .setCustomerKey("CUSTOMER_KEY")     // уникальный ID пользователя для сохранения данных его карты
        .setReceipt(receipt)
        .setData(dataMap)
        .setTheme(themeId)
        .setChargeMode(chargeMode)
        .setCameraCardScanner(new CameraCardIOScanner()))
        .startActivityForResult(this, REQUEST_CODE_PAYMENT);

Данные объекты при их наличии будут переданы на сервер с помощью метода API Init, где можно посмотреть детальное описание объекта Receipt

[1] Рекуррентный платеж может производиться для дальнейшего списания средств с сохраненной карты, без ввода ее реквизитов. Эта возможность, например, может использоваться для осуществления платежей по подписке.

[2] Безопасная клавиатура используется вместо системной и обеспечивает дополнительную безопасность ввода, т.к. сторонние клавиатуры на устройстве клиента могут перехватывать данные и отправлять их злоумышленнику.

Экран привязки карт

Для запуска привязки карт необходимо запустить AttachCardFormActivity. Активити должна быть настроена на обработку конкретного платежа, поэтому для получения интента для ее запуска необходимо вызвать цепочку из методов AttachCardFormActivity#init, AttachCardFormActivity#prepare:

AttachCardFormActivity
        .init("TERMINAL_KEY", "PASSWORD", "PUBLIC_KEY") // данные продавца
        .prepare(
                "CUSTOMER_KEY",                         // уникальный ID пользователя для сохранения данных его карты                             
                CheckType.THREE_DS,                     // тип привязки карты
                true,                                   // флаг использования безопасной клавиатуры
                "E-MAIL")                               // e-mail клиента
        .startActivityForResult(this, ATTACH_CARD_REQUEST_CODE);

По аналогии с PayFormActivity, форму привязки карты можно кастомизировать

AttachCardFormActivity
        .init("TERMINAL_KEY", "PASSWORD", "PUBLIC_KEY") // данные продавца
        .prepare("CUSTOMER_KEY", CheckType.THREE_DS, true, "E-MAIL")   
        .setData(data)
        .setTheme(themeId)
        .setCameraCardScanner(new CameraCardIOScanner()))
        .startActivityForResult(this, ATTACH_CARD_REQUEST_CODE);

Темы

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

На обоих активити используется одна и та же тема, просто на AttachCardFormActivity не используются некоторые аттрибуты.

Структура

SDK состоит из следующих модулей:

Core

Является базовым модулем для работы с Tinkoff Acquiring API. Модуль реализует протокол взаимодействия с сервером и позволяет не осуществлять прямых обращений в API. Не зависит от Android SDK и может использоваться в standalone Java приложениях.

Основной класс модуля - AcquiringSdk - предоставляет фасад для взаимодействия с Tinkoff Acquiring API. Для работы необходимы ключи и пароль продавца (см. Подготовка к работе).

UI

Содержит интерфейс, необходимый для приема платежей через мобильное приложение.

Основной класс - PayFormActivity - экран с формой оплаты, который позволяет:

• просматривать информацию о платеже
• вводить или сканировать реквизиты карты для оплаты
• проходить 3DS подтверждение
• управлять списком ранее сохраненных карт

Google Pay

Документация

Для включения Google Pay необходимо:

Добавить мета информацию в манифест приложения

    <meta-data
        android:name="com.google.android.gms.wallet.api.enabled"
        android:value="true" />

Сконфигурировать необходимые параметры

    GooglePayParams googlePayParams = new GooglePayParams.Builder()
                    .setMerchantName(getString(R.string.merchant_name))
                    .setAddressRequired(false)
                    .setPhoneRequired(false)
                    .setTheme(WalletConstants.THEME_LIGHT)
                    .setBuyButtonAppearance(WalletFragmentStyle.BuyButtonAppearance.ANDROID_PAY_LIGHT)
                    .setEnvironment(WalletConstants.ENVIRONMENT_TEST)
                    .build();

Передать параметры в PayFormActivity

PayFormActivity
        .init(TERMINAL_KEY, PASSWORD, PUBLIC_KEY) // данные продавца
        .prepare()
        .setGooglePayParams(params)
        .setCustomerKey(CUSTOMER_KEY)
        .startActivityForResult(this, REQUEST_CODE_PAYMENT);

Card-IO

Модуль для сканирование карты с помощью камеры с помощью библиотеки Card-IO.

Proguard

-keep class ru.tinkoff.acquiring.sdk.views.** { *; }

Sample

Содержит пример интеграции Tinkoff Acquiring SDK и модуля сканирования Card-IO в мобильное приложение по продаже книг.

Поддержка

• Просьба, по возникающим вопросам обращаться на [email protected]
• Баги и feature-реквесты можно направлять в раздел issues
• JavaDoc