Библиотека позволяет встроить прием платежей в мобильные приложения на Android и работает как дополнение к API Яндекс.Кассы.
В мобильный SDK входят готовые платежные интерфейсы (форма оплаты и всё, что с ней связано). С помощью SDK можно получать токены для проведения оплаты с банковской карты, через Google Pay, Сбербанк Онлайн или из кошелька в Яндекс.Деньгах.
Посмотреть, как выглядят платежные интерфейсы и как проходит процесс оплаты, можно в специальном демо-приложении.
Установите приложение на ваше устройство и пройдите весь процесс так, как это сделают ваши пользователи: нажмите на кнопку Купить, введите данные банковской карты или кошелька на Яндексе.
Приложение позволяет воспроизводить разные сценарии оплаты.
Приложение нужно устанавливать со смартфона
Скачивая демо-приложение, вы принимаете лицензионное соглашение.
Для начала вам нужно реализовать прием платежей по API Яндекс.Кассы. После этого:
- Сообщите менеджеру, что собираетесь проводить платежи с помощью мобильного SDK.
- Выпустите ключ для клиентских приложений в личном кабинете (эту возможность включает менеджер по запросу).
- Добавьте SDK в приложение и настройте выпуск одноразовых платежных токенов.
- Реализуйте отправку одноразовых токенов из мобильного приложения в вашу систему (например, в бэкенд вашего сайта, который отвечает за работу с Яндекс.Кассой).
- Проводите платежи с использованием платежных токенов через API Яндекс.Кассы.
Чтобы использовать мобильный SDK, подключите зависимости через Gradle.
Дополнительно настройте приложение, если собираетесь принимать оплату из кошелька в Яндекс.Деньгах или продавать в приложении цифровые товары.
Для подключения библиотеки пропишите зависимости в
build.gradle
вашего модуля.Groovy
repositories { maven { url 'https://dl.bintray.com/yandex-money/maven' } } dependencies { implementation 'com.yandex.money:checkout:$versionName' }
Чтобы принимать платежи из кошельков в Яндекс.Деньгах, необходима авторизация в Яндексе.
- Зарегистрируйте свое приложение в Яндекс.OAuth и сохраните ID. При регистрации:
- введите название приложения;
- в разделе Платформы выберите Android приложение и заполните настройки для Android;
- в разделе API Яндекс.Паспорта выберите Доступ к логину, имени, фамилии и полу, чтобы имя пользователя отображалось без ошибок.
- Подключите YandexLoginSDK.
Groovy
android { defaultConfig { manifestPlaceholders = [YANDEX_CLIENT_ID:"ваш идентификатор приложения в Яндекс.OAuth"] } } repositories { mavenCentral() } dependencies { implementation "com.yandex.android:authsdk:$authsdkVersion" }
Если в приложении вы продаете цифровые товары, отключите Google Pay (c его помощью нельзя платить за софт и другие товары).
Для этого добавьте в AndroidManifest соответствующий код.
Java
<meta-data android:name="com.google.android.gms.wallet.api.enabled" tools:node="remove" />
Вся работа с библиотекой происходит через обращения к классу
ru.yandex.money.android.sdk.Checkout
.С помощью SDK вы можете:
- токенизировать платежные данные пользователя;
- при оплате банковской картой сканировать данные карты и обрабатывать 3-D Secure;
- настраивать интерфейс платежной формы.
Токенизацию данных можно протестировать.
Для запуска токенизации вызовите метод
Checkout.createTokenizeIntent ()
. Метод вернет Intent
, который нужно запустить в startActivityForResult ()
. После этого управление процессом перейдет в мобильный SDK.Java
class MyActivity extends android.support.v7.app.AppCompatActivity { ... void timeToStartCheckout() { PaymentParameters paymentParameters = new PaymentParameters( new Amount(BigDecimal.TEN, Currency.getInstance("RUB")), "Название товара", "Описание товара", "live_AAAAAAAAAAAAAAAAAAAA", "12345" ); Intent intent = Checkout.createTokenizeIntent(this, paymentParameters); startActivityForResult(intent, REQUEST_CODE_TOKENIZE); } }
Входные параметры метода
Параметр | Тип | Описание |
---|---|---|
context | Context | Контекст приложения |
paymentParameters | PaymentParameters | Параметры платежа |
testParameters | TestParameters | Параметры для отладки |
uiParameters | UiParameters | Настройка интерфейса |
Поля PaymentParameters
Обязательные поля PaymentParameters
Параметр | Тип | Описание |
---|---|---|
amount | Amount | Объект, содержащий сумму заказа и валюту. |
title | String | Название товара. |
subtitle | String | Описание товара. |
clientApplicationKey | String | Ключ для клиентских приложений из личного кабинета Яндекс.Кассы. |
shopId | String | Идентификатор магазина в Яндекс.Кассе. |
Необязательные поля PaymentParameters
Параметр | Тип | Описание |
---|---|---|
paymentMethodTypes | PaymentMethodType | Способы оплаты, доступные пользователю в приложении. Если оставить поле пустым или передать в нем null , мобильный SDK будет использовать все доступные способы оплаты. |
gatewayId | String | Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта. Необязательный параметр. |
customReturnUrl | String | URL страницы, на которую надо вернуться после 3-D Secure. Только HTTPS. Необходим, только если вы используете собственный Activity при реализации 3-D Secure. Если вы используете Activity мобильного SDK, не задавайте этот параметр. |
userPhoneNumber | String | Номер телефона пользователя для оплаты через Сбербанк Онлайн. Используется для автозаполнения платежной формы. Указывается в формате: «+7XXXXXXXXXX». |
googlePayParameters | GooglePayParameters | Настройки для оплаты через Google Pay |
Поля класса Amount
Параметр | Тип | Описание |
---|---|---|
value | BigDecimal | Сумма заказа. Максимальное и минимальное значения зависят от выбранного способа оплаты и настроек вашего аккаунта в Яндекс.Кассе. |
currency | Currency | Валюта. |
Значения PaymentMethodType
- YANDEX_MONEY— Яндекс.Деньги (платежи из кошелька или привязанными картами);
- BANK_CARD— банковские карты (карты можно сканировать);
- SBERBANK— Сбербанк Онлайн (с подтверждением оплаты по смс);
- GOOGLE_PAY— Google Pay.
Поля класса GooglePayParameters
Параметр | Тип | Описание |
---|---|---|
allowedCardNetworks | Set (GooglePayCardNetwork) | Платежные системы, карты которых можно использовать в вашем приложении для оплаты через Google Pay. Возможные значения: MASTERCARD , VISA , AMEX , DISCOVER , JCB , INTERAC , OTHER |
Результат токенизации будет возвращен в
onActivityResult ()
. Возможные коды результата (resultCode
):- Activity.RESULT_OK— токенизация прошла успешно;
- Activity.RESULT_CANCELED— пользователь отменил токенизацию.
В случае успешной токенизации SDK вернет платежный токен и способ оплаты.
Чтобы получить токен, вызовите метод
Checkout.createTokenizationResult ()
и передайте в нем Intent
из onActivityResult ()
.Java
public final class MainActivity extends AppCompatActivity { ... @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == REQUEST_CODE_TOKENIZE) { switch (resultCode) { case RESULT_OK: // successful tokenization TokenizationResult result = Checkout.createTokenizationResult(data); ... break; case RESULT_CANCELED: // user canceled tokenization ... break; } } } }
Checkout.createTokenizationResult ()
возвращает
TokenizationResult
.Параметры TokenizationResult
Параметр | Тип | Описание |
---|---|---|
paymentToken | String | Платежный токен. |
paymentMethodType | PaymentMethodType | Способ оплаты. |
Значения
PaymentMethodType
:- YANDEX_MONEY— Яндекс.Деньги (платежи из кошелька или привязанными картами);
- BANK_CARD— банковские карты;
- SBERBANK— Сбербанк Онлайн (с подтверждением оплаты по смс);
- GOOGLE_PAY— Google Pay.
Вы можете отладить токенизацию с помощью тестового режима и логирования.
Тестовый режим позволяет проверить работу SDK без реальных данных. Вы можете посмотреть, как работает SDK в разных условиях, и сгенерировать тестовый токен. В тестовом режиме мобильному SDK не нужен доступ в интернет.
Тестовый токен нельзя использовать для реальных платежей.
Мобильный SDK логирует все операции. Вы можете включить отображение логов для реальных и тестовых платежей. Все логи начинаются с тега 'Yandex.Checkout.SDK'.
Для отладки токенизации в вызов
Checkout.createTokenizeIntent ()
добавьте объект TestParameters
.Java
class MyActivity extends android.support.v7.app.AppCompatActivity { ... void timeToStartCheckout() { PaymentParameters paymentParameters = new PaymentParameters(...); TestParameters testParameters = new TestParameters(true, true, new MockConfiguration(false, true, 5)); Intent intent = Checkout.createTokenizeIntent(this, paymentParameters, testParameters); startActivityForResult(intent, REQUEST_CODE_TOKENIZE); } }
Поля класса
TestParameters:
Параметр | Тип | Описание |
---|---|---|
showLogs | Boolean | Отображение логов мобильного SDK. |
mockConfiguration | MockConfiguration | Настройки тестовой конфигурации. Если этот параметр присутствует, мобильный SDK будет работать в офлайн-режиме и генерировать тестовый токен. |
Поля класса
MockConfiguration
:Параметр | Тип | Описание |
---|---|---|
completeWithError | Boolean | Токенизация всегда возвращает ошибку. |
paymentAuthPassed | Boolean | Пользователь всегда авторизован. |
linkedCardsCount | Int | Количество карт, привязанных к кошельку пользователя. |
Интерфейс мобильного SDK можно настраивать с помощью объекта
UiParameters
.Поля класса
UiParameters
:Параметр | Тип | Описание |
---|---|---|
showLogo | Boolean | Показать или скрыть логотип Яндекс.Кассы на экране способов оплаты. |
colorScheme | ColorScheme | Цветовая схема приложения. |
Поля класса
ColorScheme
:Параметр | Тип | Описание |
---|---|---|
primaryColor | ColorInt | Основной цвет, который будет использоваться в качестве фона кнопок и других элементов интерфейса. Не рекомендуется выбирать слишком светлые оттенки (в приложении белый фон, и светлые элементы интерфейса на нем потеряются) и красный цвет (это цвет ошибки). |
Java
class MyActivity extends android.support.v7.app.AppCompatActivity { ... void timeToStartCheckout() { PaymentParameters paymentParameters = new PaymentParameters(...); UiParameters uiParameters = new UiParameters(true, new ColorScheme(Color.rgb(0, 114, 245))); Intent intent = Checkout.createTokenizeIntent(this, paymentParameters, new TestParameters(), uiParameters); startActivityForResult(intent, REQUEST_CODE_TOKENIZE); } }
В мобильном SDK есть Activity для обработки 3-D Secure —
Checkout.create3dsIntent ()
.Если вы обрабатываете 3-D Secure с помощью Activity мобильного SDK, не указывайте
PaymentParameters.customReturnUrl
при вызове Checkout.createTokenizeIntent ()
.
Входные параметры для
Checkout.create3dsIntent ()
:Параметр | Тип | Описание |
---|---|---|
context | Context | Контекст для создания Intent . |
url | String | URL для перехода на 3-D Secure. |
colorScheme | ColorScheme | Цветовая схема. |
Результат работы 3-D Secure можно получить в
onActivityResult ()
. Возможные коды результата (resultCode
):- Activity.RESULT_OK— аутентификация по 3-D Secure прошла успешно;
- Activity.RESULT_CANCELED— экран 3-D Secure был закрыт (например, пользователь нажал на кнопку Назад);
- Checkout.RESULT_ERROR— не удалось пройти аутентификацию по 3-D Secure.
Java
class MyActivity extends android.support.v7.app.AppCompatActivity { void timeToStart3DS() { Intent intent = Checkout.create3dsIntent( this, "https://3dsurl.com/" ); startActivityForResult(intent, 1); } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == 1) { switch (resultCode) { case RESULT_OK: // Аутентификация по 3-D Secure прошла успешно break; case RESULT_CANCELED: // Экран 3-D Secure был закрыт break; case Checkout.RESULT_ERROR: // Во время 3-D Secure произошла какая-то ошибка //(например, нет соединения), // более подробную информацию можно посмотреть в data: // data.getIntExtra(Checkout.EXTRA_ERROR_CODE) — код ошибки из WebViewClient.ERROR_* или Checkout.ERROR_NOT_HTTPS_URL // data.getStringExtra(Checkout.EXTRA_ERROR_DESCRIPTION) — описание ошибки (может отсутствовать) // data.getStringExtra(Checkout.EXTRA_ERROR_FAILING_URL) — URL, по которому произошла ошибка (может отсутствовать) break; } } } }
Создайте
Activity
, обрабатывающую action ru.yandex.money.android.sdk.action.SCAN_BANK_CARD
.XML
<activity android:name=".ScanBankCardActivity"> <intent-filter> <action android:name="ru.yandex.money.android.sdk.action.SCAN_BANK_CARD"/> </intent-filter> </activity>
В этой
Activity
запустите вашу библиотеку для сканирования карты.
Полученный номер карты передайте c помощью Intent
.Если сканирование прошло успешно, укажите
Activity.RESULT_OK
.
Java
public class ScanBankCardActivity extends Activity { private void onScanningDone(final String cardNumber, final int expirationMonth, final int expirationYear) { final Intent result = Checkout.createScanBankCardIntent(cardNumber, expirationMonth, expirationYear); setResult(Activity.RESULT_OK, result); finish(); } }