NAV Navbar

YandexCheckout.js

YandexCheckout.js — это JavaScript-библиотека, с помощью которой можно создавать кастомизированные формы для приема платежей на своей стороне. Работает как дополнение к API Яндекс.Кассы.

Пока в библиотеке есть только формы для приема платежей с банковских карт, в планах — добавить другие способы оплаты, доступные в Яндекс.Кассе (например, оплату через Сбербанк Онлайн или Apple Pay).

С помощью этой библиотеки вы сможете:

Инициализация

Ссылка на библиотеку

<script src="https://static.yandex.net/checkout/js/v1/"></script>

YandexCheckout.js подключается только с серверов https://static.yandex.net. Так чувствительные данные ваших клиентов всегда будут в безопасности.

Чтобы начать работу с API, загрузите основную библиотеку.

Аутентификация

Пример создания YandexCheckout

const checkout = YandexCheckout(<Идентификатор магазина>);

Создайте экземпляр объекта YandexCheckout.

Используйте конструкцию YandexCheckout(<Идентификатор магазина>)

<Идентификатор магазина> — shopId вашего магазина в Яндекс.Кассе (выдается при подключении, его можно посмотреть в личном кабинете Яндекс.Кассы).

После этого можно будет создать инстанс от YandexCheckout и использовать его для генерации токена с данными банковской карты.

Конфигурация

Пример инициализации с выбором языка

const checkout = YandexCheckout(<Идентификатор магазина>, {
    language: 'en'
});

Вы можете показывать пользователям сообщения и ошибки по-русски или по-английски. По умолчанию мы отображаем ошибки на русском языке.

Параметр Описание Тип Валидация
language Язык пользовательских ошибок. Возможные значения: en и ru string 2 символа

Токенизация

Пример генерации токена

checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(res => {
    if (res.status === 'success') {
        const { paymentToken } = res.data.response;

        return paymentToken;
    }
});

Сгенерируйте платежный токен с данными банковской карты. Токен можно использовать для проведения оплаты по API Яндекс.Кассы.

Параметры метода

Пример валидных данных

checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'success') {
        const { paymentToken } = response.data.response;

        // eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc...
        return paymentToken;
    }
});

Пример невалидных данных:

checkout.tokenize({
    number: document.querySelector('.number').value,
    cvc: document.querySelector('.cvc').value,
    month: document.querySelector('.expiry_month').value,
    year: document.querySelector('.expiry_year').value
}).then(response => {
    if (response.status === 'error') {
        // validation_error
        const { type } = response.error;

        /*
            [
                {
                    code: 'invalid_expiry_month',
                    message: 'Невалидное значение месяца'
                },
                {
                    code: 'invalid_cvc',
                    message: 'Невалидное значение CVC'
                }
            ]
        */
        const { params } = response.error;

        return response;
    }
});
Параметр Описание Тип Валидация
number * Номер банковской карты string 16 символов, только числа
cvc * Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне карты string 3, 4 символа, только числа
month * Месяц истечения срока действия карты string 2 символа, только числа
year * Год истечения срока действия карты string 2 символа, только числа

Ошибки

Библиотека возвращает два типа ошибок: ошибки валидации данных на форме и ошибки, связанные с работой YandexCheckout.js.

Ошибки валидации возникают, когда пользователь неправильно вводит данные банковской карты: эти ошибки необходимо показывать пользователю.

Остальные ошибки возвращаются при проблемах с инициализацией библиотеки или взаимодействием библиотеки с сервером Яндекс.Кассы. Такие ошибки показывать пользователю не нужно.

try {
    const checkout = YandexCheckout(); // Не передан shopId
} catch(error) {
    // Формат ответа см. в разделе «Ошибки»
}

Формат выдачи ошибок

{
    status: 'error',
    error: {
        type: string,
        message: ?string,
        status_code: number,
        code: ?string,
        params: Array<{
            code: string,
            message: string
        }>
    }
}

Пример 1. Ошибка при подключении к серверу

{
    status: 'error',
    error: {
        type: 'api_connection_error',
        message: 'Ошибка в подключении сервера',
        status_code: 402,
        code: 'processing_error',
        params: []
    }
}

Пример 2. Ошибка валидации

{
    status: 'error',
    error: {
        type: 'validation_error',
        message: undefined,
        status_code: 400,
        code: undefined,
        params: [
            {
                code: 'invalid_number',
                message: 'Неверный номер карты'
            },
            {
                code: 'invalid_expiry_month',
                message: 'Невалидное значение месяца'
            }
        ]
    }
}

Коды ответа

Код ответа Значение
400 Ошибка валидации
401 Ошибка аутентификации
402 Ошибка подключения к API Яндекс.Кассы
404 Запрашиваемый ресурс не найден
500 Непредвиденная ошибка

YandexCheckout.js поддерживает стандартные коды ответа:

Типы ошибок

Тип ошибки Значение
authentication_error Проблема с аутентификацией
api_connection_error Не получилось установить соединение с Яндекс.Кассой
api_error Произошла ошибка на стороне Яндекс.Кассы
card_error Что-то не так с банковской картой
invalid_request_error Неверные данные запроса
validation_error Ошибка валидации, какое-то из полей на форме ввода банковской карты введено неверно

Коды ошибок

Код ошибки Значение
invalid_number Невалидный номер карты
invalid_expiry_month Неверный месяц истечения срока действия карты
invalid_expiry_year Неверный год истечения срока действия карты
invalid_cvc Неверный CVC-код
expired_card Карта просрочена
card_declined Карта отклонена
processing_error Ошибка при проверке карты
missing Непредвиденная ошибка

YandexCheckout UI

UI-библиотека, позволяет показывать пользователям готовую форму оплаты с банковской карты. Работает вместе с YandexCheckout.js.

Что умеет форма:

Инициализация

Подключаем скрипт на страницу

<script src="https://static.yandex.net/checkout/ui/v1/"></script>

Создаем инстанс от YandexCheckoutUI

const $checkout = YandexCheckoutUI(123456);

Где 123456 — ваш shopId

Библиотека подключается только через CDN.

Подключите скрипт из CDN. Библиотека будет доступна в глобальной области видимости под именем YandexCheckoutUI.

После этого вы можете создать инстанс от YandexCheckoutUI и использовать $checkout для генерации токена с данными банковской карты.

Конфигурация

Пример с настройкой YandexCheckoutUI

const $checkout = YandexCheckoutUI(123456, {
    language: 'en',
    domSelector: '.my-selector',
    amount: 99.99
});

Вы можете настроить форму:

Параметр Описание Тип По умолчанию
language Язык интерфейса (надписи на форме, ответы, ошибки). Возможные значения: en или ru string ru
amount Сумма оплаты, которая отображается на форме number 0
isRecurrent отрисовать на форме сообщение о том, что будут производиться безакцептные списания (рекурренты) boolean false

Возможные значения

{
    // язык вывода ответов
    language: string ('en' | 'ru') ['ru'],

    // стоимость, которую нужно показать на форме
    amount: number ['0'],

    // Будут производиться реруррентные платежи
    isRecurrent: true [false]
}

Методы

Метод Описание Принимает Возвращает
.open Показывает форму {void}
.close Скрывает форму {void}
.on Включает подписку на события yc_error, yc_success {void}
.showLantern Выводит сообщение для пользователя text string {void}
.hideLantern Скрывает сообщение для пользователя {void}
.showLantern Переключает состояние сообщения для пользователя text string {void}
.chargeSuccessful Сообщает форме об успешном ответе от API Яндекс.Кассы text string {void}
.chargeFailful Сообщает форме об ошибке от API Яндекс.Кассы text string {void}

.open

Показывает платежную форму.

const $checkout = YandexCheckoutUI(123456);
$checkout.open();

.close

Скрывает платежную форму.

const $checkout = YandexCheckoutUI(123456);
$checkout.close();

.on

Позволяет подписаться на события, возникающие при работе с библиотекой.

Доступные подписки:

Событие Описание Возвращает
yc_error Произошла ошибка любого рода Объект точно такого же вида, что и ошибка в Yandex.CheckoutJS
yc_success Токен успешно создан Объект точно такого же вида, что и успешный ответ в Yandex.CheckoutJS

Пример с ошибкой

$checkout.on('yc_error', response => {
    /*
    {
        status: 'error',
        error: {
            type: 'validation_error',
            message: undefined,
            status_code: 400,
            code: undefined,
            params: [
                {
                    code: 'invalid_number',
                    message: 'Неверный номер карты'
                },
                {
                    code: 'invalid_expiry_month',
                    message: 'Невалидное значение месяца'
                }
            ]
        }
    }
    */
});

Пример успешного создания токена

$checkout.on('yc_success', response => {
    /*
    {
        status: 'success',
        data: {
            message: 'Токен для оплаты создан',
            status_code: 200,
            type: 'payment_token_created',
            response: {
                paymentToken: 'eyJlbmNyeXB0ZWRNZXNzYWdlIjoiWlc1amNubHdkR1ZrVFdWemMyRm5aUT09IiwiZXBoZW1lcmFsUHVibGljS2V5IjoiWlhCb1pXMWxjbUZzVUhWaWJHbGpTMlY1IiwidGFnIjoiYzJsbmJtRjBkWEpsIn0K'
            }
        }
    }
    */
    console.log(response);
});

.showLantern

Показывает пользователю сообщение над формой (если произошла какая-нибудь ошибка при запросах по API Яндекс.Кассы).

Параметр Тип Описание
text string Текст ошибки
const $checkout = YandexCheckoutUI(123456);
$checkout.showLantern('Текст ошибки');

.hideLantern

Позволяет скрыть сообщение с ошибкой.

const $checkout = YandexCheckout(123456);
$checkout.hideLantern();

.toggleLantern

Открывает или скрывает сообщение с ошибкой.

Параметр Тип Описание
text string Текст ошибки
const $checkout = YandexCheckoutUI(123456);
$checkout.toggleLantern('Текст ошибки');

.chargeSuccessful

Сообщает форме об успешном ответе от API Яндекс.Кассы.

После вызова этого метода:

const $checkout = YandexCheckoutUI(123456);

// Открываем форму
$checkout.open();

// Токен успешно создан
$checkout.on('yc_success', () => {
    // Запрос к API Яндекс.Кассы
    // ...

    // Если оплата прошла успешно, то вызываем метод
    $checkout.chargeSuccessful();
});

.chargeFailful

Сообщает платежной форме о том, что от API Яндекс.Кассы пришла ошибка.

После вызова этого метода пользователю показывается сообщение с ошибкой.

Параметр Тип Описание
text string Текст ошибки
const $checkout = YandexCheckoutUI(123456);

// Открываем форму
$checkout.open();

// Токен успешно создан
$checkout.on('yc_success', () => {
    // Запрос к API Яндекс.Кассы
    // ...

    // Оплата не прошла
    $checkout.chargeFailful();
});

Мобильные SDK

Эти библиотеки позволяют встроить прием платежей в мобильные приложения на iOS и Android, работают вместе с API Яндекс.Кассы. В SDK входят готовые платежные интерфейсы (форма оплаты и все, что с ней связано).

Скачать мобильный SDK:

Демо-приложение

Посмотреть, как выглядят платежные интерфейсы и как проходит процесс оплаты, можно в специальном демо-приложении. Установите приложение на ваше устройство и пройдите весь процесс так, как это сделают ваши пользователи: нажмите на кнопку Купить, введите данные банковской карты или кошелька на Яндексе. Приложение позволяет воспроизводить разные сценарии оплаты.

Скачать демо-приложение (устанавливается со смартфона):

Переходя по этим ссылкам, вы принимаете лицензионное соглашение

Работа с SDK

Для начала вам нужно реализовать прием платежей по API Яндекс.Кассы. После этого:

  1. Cообщите менеджеру, что собираетесь проводить платежи с помощью мобильного SDK.

  2. Загрузите SDK для Android или для iOS.

  3. Выпустите ключ для клиентских приложений в личном кабинете (эту возможность включает менеджер по запросу).

  4. Добавьте SDK в приложение и настройте выпуск одноразовых платежных токенов.

  5. Реализуйте отправку одноразовых токенов из мобильного приложения в вашу систему (например, в бэкенд вашего сайта, который отвечает за работу с Яндекс.Кассой).

  6. Проводите платежи с использованием платежных токенов через API Яндекс.Кассы.

SDK для iOS

Подключение

Установите CocoaPods

$ gem install cocoapods

Добавьте зависимости в Podfile

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'YandexCheckoutPayments',
        :git => 'https://github.com/yandex-money/yandex-checkout-payments-swift.git',
        :tag => '<tag>'
end

Выполните команду в каталоге с проектом

$ pod install

Добавьте библиотеку TrustDefender.framework в папку Frameworks

App
├─ Pods
└─ Frameworks
   └─ TrustDefender.framework

Требования: iOS 8.0, 9, 10 и 11

Загрузите библиотеки Яндекс.Кассы для установки SDK.

Подключить библиотеку можно через CocoaPods — это менеджер зависимостей для Swift и Objective-C проектов Cocoa.

  1. Подключите библиотеку через CocoaPods.
  2. Добавьте библиотеку TrustDefender.framework к вашему проекту.

Проведение платежа

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

После этого можно проводить платежи:

  1. Подготовьтесь к приему платежа через мобильный SDK.
  2. Когда пользователь выберет способ оплаты и введет все необходимые данные, вы сможете получить токен.
  3. Отправьте токен в вашу систему.
  4. Создайте платеж с токеном по API Яндекс.Кассы.

Шаг1. Подготовка к приему платежа

Пример создания TokenizationModuleInputData

let clientApplicationKey = "<Ключ для клиентских приложений>"
let amount = Amount(value: 999.99, currency: .rub)
let inputData = TokenizationModuleInputData(clientApplicationKey: clientApplicationKey,
                                            shopName: "Космические объекты",
                                            purchaseDescription: """
                                                    Комета повышенной яркости, период обращения — 112 лет
                                                    """,
                                            amount: amount)

Создайте TokenizationModuleInputData. Вам понадобится ключ для клиентских приложений из личного кабинета Яндекс.Кассы. В этой модели передаются параметры платежа (валюта и сумма), параметры платежной формы, которые увидит пользователь при оплате (способы оплаты, название магазина и описание заказа).

TokenizationModuleInputData

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

Параметр Тип Описание
clientApplicationKey String Ключ для клиентских приложений из личного кабинета Яндекс.Кассы.
amount Amount Объект, содержащий сумму заказа и валюту.
shopName String Название магазина в форме оплаты.
purchaseDescription String Описание заказа в форме оплаты.
gatewayId String Идентификатор шлюза, выдается в Яндекс.Кассе. По умолчанию nil. Необязательный, используется, если у вас несколько платежных шлюзов с разными идентификаторами.
tokenizationSettings TokenizationSettings Настройка токенизации (способы оплаты и логотип Яндекс.Кассы).
testModeSettings TestModeSettings Настройки тестового режима
cardScanning CardScanning Возможность сканировать банковские карты.
applePayMerchantIdentifier String Apple Pay merchant ID (обязательно для платежей через Apple Pay).

Состав tokenizationSettings

С помощью этой структуры можно настроить список способов оплаты и отображение логотипа Яндекс.Кассы в приложении.

Параметр Тип Описание
paymentMethodTypes PaymentMethodTypes Способы оплаты, доступные пользователю в приложении.
showYandexCheckoutLogo Bool Отвечает за отображение логотипа Яндекс.Кассы. По умолчанию логотип отображается.

Шаг 2. Получение токена

Получение токена

let viewController = TokenizationAssembly.makeModule(inputData: inputData,
                                                     moduleOutput: self)
present(viewController, animated: true, completion: nil)

Создайте ViewController из TokenizationAssembly и выведите его на экран.

Шаг 3. Платеж с токеном

Отправка токена и выбранного способа оплаты в вашу систему

func tokenizationModule(_ module: TokenizationModuleInput,
                        didTokenize token: Tokens,
                        paymentMethodType: PaymentMethodType) {
    DispatchQueue.main.async { [weak self] in
        guard let strongSelf = self else { return }
        strongSelf.dismiss(animated: true)
    }
    // Отправьте токен в вашу систему
}

func didFinish(on module: TokenizationModuleInput) {
    DispatchQueue.main.async { [weak self] in
        guard let strongSelf = self else { return }
        strongSelf.dismiss(animated: true)
    }
}

Закройте ViewController и отправьте токен в вашу систему. Затем создайте платеж по API Яндекс.Кассы, в параметре payment_token передайте токен, полученный в SDK. Способ подтверждения при создании платежа зависит от способа оплаты, который выбрал пользователь. Он приходит вместе с токеном в paymentMethodType.

Способы оплаты

Как передать код способа оплаты в TokenizationSettings

// Создайте пустой OptionSet PaymentMethodTypes
var paymentMethodTypes: PaymentMethodTypes = []


if <Условие для банковской карты> {
    // Добавляем в paymentMethodTypes элемент `.bankCard`
    paymentMethodTypes.insert(.bankCard)
}

if <Условие для Сбербанка Онлайн> {
    // Добавляем в paymentMethodTypes элемент `.sberbank`
    paymentMethodTypes.insert(.sberbank)
}

if <Условие для Яндекс.Денег> {
    // Добавляем в paymentMethodTypes элемент `.yandexMoney`
    paymentMethodTypes.insert(.yandexMoney)
}

if <Условие для Apple Pay> {
    // Добавляем в paymentMethodTypes элемент `.applePay`
    paymentMethodTypes.insert(.applePay)
}

Способ оплаты указывается при создании TokenizationModuleInputData в параметре tokenizationSettings, в объекте paymentMethodTypes. Если вы укажете несколько способов оплаты, пользователь сможет выбрать один из них.

Сейчас в SDK для iOS доступны следующие способы оплаты:

  1. Добавьте способы оплаты, которые нужно отобразить на экране пользователя, в paymentMethodTypes.
  2. Создайте свой TokenizationSettings и передайте в него готовый paymentMethodTypes.
  3. Передайте получившийся TokenizationSettings в TokenizationModuleInputData.

Оплата любым доступным способом

Если вы не указываете способ оплаты, пользователь увидит в вашем приложении экран с набором всех доступных способов и сможет выбрать любой.

Как провести платеж любым доступным способом:

  1. Создайте TokenizationModuleInputData, в paymentMethodTypes ничего передавать не нужно.
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения, которого требует выбранный пользователем способ оплаты.

Банковская карта

Платеж банковской картой

Чтобы провести платеж банковской картой:

  1. При создании TokenizationModuleInputData передайте значение .bankCard в paymentMethodTypes.
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения Redirect (если требуется подтверждение пользователем по 3-D Secure).

Сканирование банковских карт

Как настроить CardScanning

class CardScannerProvider: CardScanning {
    weak var cardScanningDelegate: CardScanningDelegate?

    var cardScanningViewController: UIViewController? {

        // Create and return scanner view controller

        viewController.delegate = self

        return viewController
    }
}

Пример сканирования с помощью card.io

// MARK: - CardIOPaymentViewControllerDelegate

extension CardScannerProvider: CardIOPaymentViewControllerDelegate {
    public func userDidProvide(_ cardInfo: CardIOCreditCardInfo!,
                               in paymentViewController: CardIOPaymentViewController!) {
        let scannedCardInfo = ScannedCardInfo(number: cardInfo.cardNumber,
                                              expiryMonth: "\(cardInfo.expiryMonth)",
                                              expiryYear: "\(cardInfo.expiryYear)")
        cardScanningDelegate?.cardScannerDidFinish(scannedCardInfo)
    }

    public func userDidCancel(_ paymentViewController: CardIOPaymentViewController!) {
        cardScanningDelegate?.cardScannerDidFinish(nil)
    }
}

Передайте cardScanning в TokenizationModuleInputData

let inputData = TokenizationModuleInputData(clientApplicationKey: clientApplicationKey,
                                            shopName: "<Past your shop name here>",
                                            purchaseDescription: """
                                                    <Past description of purchase here>
                                                    """,
                                            amount: amount,
                                            cardScanning: CardScannerProvider())

Если хотите, чтобы пользователи смогли сканировать банковские карты при оплате:

  1. Настройте протокол CardScanning.
  2. Выполните сканирование с помощью CardScanerProvider (например, card.io).
  3. Затем передайте CardScannerProvider в объекте cardScanning в TokenizationModuleInputData.

Яндекс.Деньги

Как настроить авторизацию в Яндексе

Добавьте эти строки в info.plist

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>yandexauth</string>
  <string>yandexauth2</string>
</array>

Добавьте эти строки в AppDelegate

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    do {
        try YandexLoginService.activate(withAppId: <ID из Яндекс.OAuth>)
    } catch {
        // process error
    }
}

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    YandexLoginService.processUserActivity(userActivity)
    return true
}

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplicationOpenURLOptionsKey: Any]) -> Bool {
    return YandexLoginService.handleOpen(url, sourceApplication: options[.sourceApplication] as? String)
}

Чтобы принимать платежи из кошельков в Яндекс.Деньгах, необходима авторизация в Яндексе.

  1. Зарегистрируйте свое приложение в Яндекс.OAuth и сохраните ID.

  2. Добавьте две URL-схемы в info.plist.

  3. В своем проекте в разделе Capabilities включите Associated Domains и добавьте домен по шаблону: applinks:yx<ID из Яндекс.OAuth>.oauth.yandex.ru. Например, если ваш ID из Яндекс.OAuth — 333, домен будет таким: applinks:yx333.oauth.yandex.ru.

  4. Добавьте код из примера в AppDelegate.

Платеж из кошелька в Яндекс.Деньгах

Чтобы провести платеж из кошелька:

  1. При создании TokenizationModuleInputData передайте значение .yandexMoney в paymentMethodTypes.
  2. Получите токен.
  3. Создайте платеж по API Яндекс.Кассы со способом подтверждения Redirect
    (если требуется подтверждение пользователем).

Apple Pay

Обмен сертификатами с Apple и Яндекс.Кассой

Чтобы подключить этот способ оплаты, нужно передать Яндекс.Кассе сертификат, с помощью которого Apple будет шифровать данные банковских карт. Для этого:

  1. Напишите менеджеру и попросите создать для вас запрос на сертификат (CSR).
  2. Загрузите CSR в панели разработчика Apple.
  3. Скачайте получившийся сертификат и пришлите менеджеру.

Подробная инструкция (см. раздел 2 «Обмен сертификатами с Apple»)

Платеж через Apple Pay

Чтобы провести платеж через Apple Pay:

  1. При создании TokenizationModuleInputData передайте в paymentMethodTypes значение .apple_pay, в applePayMerchantIdentifier – ваш Apple Pay merchant ID.
  2. Получите токен.
  3. Создайте платеж по API Яндекс.Кассы без подтверждения.

Сбербанк Онлайн

С помощью SDK можно провести платеж через «Мобильный банк» Сбербанка — с подтверждением оплаты по смс:

  1. При создании TokenizationModuleInputData передайте значение .sberbank в paymentMethodTypes.
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения External.

Тестовый режим

Пример настроек для тестового режима


let monetaryAmount = MonetaryAmount(value: 10,
                                    currency: .rub)

testModeSettings = TestModeSettings(paymentAuthorizationPassed: true,
                                    cardsCount: 5,
                                    charge: monetaryAmount ,
                                    enablePaymentError: false)

Тестовый режим позволяет проверить работу SDK без реальных данных.
Для запуска тестового режима необходимо создать testModeSettings и передать в TokenizationModuleInputData.

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

Параметр Тип Описание
paymentAuthorizationPassed Bool Логическое значение, определяющее, завершена ли платежная авторизация при оплате через кошелек Яндекс.Денег.
cardsCount Int Количество карт, привязанных к кошельку в Яндекс.Деньгах.
charge MonetaryAmount Сумма и валюта платежа.
enablePaymentError Bool Если передано true, платеж пройдет с ошибкой. По умолчанию false.

SDK для Android

Подключение

Добавьте репозиторий и зависимости

repositories {
    maven { url "https://dl.bintray.com/yandex-money/maven" }
}
dependencies {
    implementation 'ru.yandex.money:msdk-android:1.0.0'
}

Требования: Android 4.0 (API 14) и выше

Добавьте репозиторий и пропишите зависимости в файле build.gradle в вашем проекте.

Вся работа с библиотекой происходит через обращение к классу ru.yandex.money.android.sdk.Checkout.

Проведение платежа

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

Чтобы провести платеж:

  1. Подключите библиотеку к фрагменту или Activity.
  2. Запустите токенизацию.
  3. Когда пользователь выберет способ оплаты и введет все необходимые данные, вы получите платежный токен.
  4. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения, который требует выбранный способ оплаты.

Шаг 1. Подключение библиотеки к фрагменту или Activity

Пример

public final class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Checkout.attach(getSupportFragmentManager());
    }

    @Override
    protected void onDestroy() {
        Checkout.detach();
        super.onDestroy();
    }
}

Для подключения интерфейса вызовите метод Checkout.attach() до начала токенизации (желательно вызвать его сразу после создания фрагмента или Activity, из которого будет произведен вызов метода).

Во время уничтожения фрагмента или Activity вызовите Checkout.detach().

Checkout.attach()

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

Параметр Описание
supportFragmentManager (FragmentManager) Менеджер фрагментов.

Шаг 2. Запуск токенизации

Запуск токенизации

class MyActivity extends AppCompatActivity {
    // Ваш код

    void timeToStartCheckout() {
        Checkout.tokenize(
        new Amount(new BigDecimal("10.0"), Currency.getInstance("RUB")),
        new ShopParameters(
            "<Название магазина>",
            "<Описание магазина>",
            "<Ключ для клиентских приложений>",
            paymentMethodTypes, // разрешенные способы оплаты (если передать пустое множество, покупатель увидит все способы)
            enableGooglePay, // включить Google Pay (нужно согласовать с менеджером Яндекс.Кассы)
            shopId, // идентификатор магазина в личном кабинете (опционально, нужен для Google Pay)
            gatewayId, // идентификатор шлюза (опционально, нужен, если вы используете разные шлюзы)
            showLogo // показывает и скрывает логотип Яндекс.Кассы
        )
    );
}
}

Для запуска процесса токенизации вызовите метод Checkout.tokenize(). После этого управление процессом перейдет в SDK.

Checkout.tokenize()

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

Параметр Тип Описание
context Context Контекст приложения.
amount Amount Сумма платежа.
shopParameters ShopParameters Параметры магазина.

Поля класса ShopParameters

Параметр Тип Описание
title String Название магазина.
subtitle String Описание магазина.
clientApplicationKey String Ключ для клиентских приложений из личного кабинета Яндекс.Кассы.
paymentMethodType PaymentMethodType Список способов оплаты. Если оставить поле пустым, пользователь увидит все доступные способы оплаты. Возможные значения: YANDEX_MONEY — кошелек в Яндекс.Деньгах, BANK_CARD — банковская карта, SBERBANK — оплата через «Мобильный банк» Сбербанка с подтверждением по смс, GOOGLE_PAY — Google Pay.
enableGooglePay Boolean Включает прием платежей через Google Pay (нужно согласовать с менеджером Яндекс.Кассы).
shopId String Идентификатор магазина в Яндекс.Кассе (нужен при платеже через Google Pay.
gatewayId String Идентификатор магазина в Яндекс.Кассе. Необязательный, используется, если у вас несколько платежных шлюзов с разными идентификаторами.
showLogo Boolean Отображает или скрывает логотип Яндекс.Кассы

Поля класса Amount

Параметр Тип Описание
value BigDecimal Сумма.
currency Currency Валюта.

Шаг 3. Получение результата токенизации

Получение токена

class MyActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        Checkout.setResultCallback(new Checkout.ResultCallback() {
            @Override
            public void onResult(@NonNull String paymentToken, @NonNull PaymentMethodType type) {
                //result handling
            }
        });
    }
}

Для получения результата токенизации используется метод Checkout.setResultCallback().

В случае успешной токенизации SDK вернет токен и способ оплаты, для которого он был получен.

Checkout.setResultCallback()

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

Checkout.ResultCallback возвращает:

Способы оплаты

Способ оплаты указывается при создании токена Checkout.tokenize() в классе PaymentMethodType. Если вы укажете несколько способов оплаты, пользователь сможет выбрать один из них.

Оплата любым доступным способом

Если вы не указываете способ оплаты, пользователь увидит в вашем приложении экран с набором всех доступных способов и сможет выбрать любой.

Как провести платеж любым доступным способом:

  1. Запустите токенизацию (Checkout.tokenize()), ShopParameters.paymentMethodTypes указывать не нужно или можно указать Collections.emptySet().
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения, которого требует выбранный пользователем способ оплаты.

Банковская карта

3-D Secure

class MyActivity extends android.support.v7.app.AppCompatActivity {

    void timeToStart3DS() {
        Intent intent = Checkout.create3dsIntent(
                this,              
                new URL("https://3dsurl.com/"),
                new URL("https://3dsend.org/")
        );
        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;
            }
        }
    }
}

Для проведения аутентификации пользователя по 3-D Secure используется метод Checkout.create3dsIntent().

Checkout.create3dsIntent()

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

Сканирование банковской карты

Создание Activity

<activity android:name=".ScanBankCardActivity">

    <intent-filter>
        <action android:name="ru.yandex.money.android.sdk.action.SCAN_BANK_CARD"/>
    </intent-filter>

</activity>
public class ScanBankCardActivity extends Activity {

    private void onScanningDone(final String cardNumber, final int expirationMonth, final int expirationYear) {

        final Intent result = Checkout.createScanBankCardResult(cardNumber, expirationMonth, expirationYear);

        setResult(Activity.RESULT_OK, result);

        finish();

    }

}
  1. Создайте Activity для обработки action ru.yandex.money.android.sdk.action.SCAN_BANK_CARD

  2. В этой Activity запустите вашу библиотеку для сканирования карты. Полученный номер карты передайте c помощью Intent. Передайте Activity.RESULT_OK, если сканирование прошло успешно.

Платеж банковской картой

  1. Запустите токенизацию (Checkout.tokenize()), укажите ShopParameters.paymentMethodTypes как Collections.singleton(PaymentMethodType.BANK_CARD).
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения Redirect (если требуется аутентификация по 3-D Secure).

Яндекс.Деньги

Авторизация в Яндексе (для платежей из кошелька)

Добавьте ID из Яндекс.OAuth в приложение

android {
    defaultConfig {
        manifestPlaceholders = [YANDEX_CLIENT_ID:"<идентификатор вашего приложения>"]
    }
}
repositories {
    mavenCentral()
}
dependencies {
    implementation 'com.yandex.android:authsdk:2.1.0'
}

Чтобы создавать токены для платежей из кошельков в Яндекс.Деньгах, необходимо зарегистрировать приложение в Яндексе. Для этого:

1.Зарегистрируйте свое приложение в Яндекс.OAuth и сохраните ID. В блоке Платформы выберите Android приложение. В блоке API Яндекс.Паспорта отметьте Доступ к логину, имени, фамилии и полу (он нужен для корректного отображения имени пользователя).

  1. Добавьте ID, который получили при регистрации в Яндекс.OAuth, в ваше приложение.

Платеж из кошелька в Яндекс.Деньгах

  1. Запустите токенизацию (Checkout.tokenize()), укажите ShopParameters.paymentMethodTypes как Collections.singleton(PaymentMethodType.YANDEX_MONEY).
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения Redirect (если требуется подтверждение платежа пользователем).

Сбербанк Онлайн

  1. Запустите токенизацию (Checkout.tokenize()), укажите ShopParameters.paymentMethodTypes как Collections.singleton(PaymentMethodType.SBERBANK).
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом подтверждения External (чтобы получить подтверждение оплаты по смс).

Google Pay

Подключение Google Pay

  1. Проведите отладку приложения в тестовом режиме Google Pay (перед Checkout.tokenize() необходимо вызвать Checkout.configureTestMode(), в переключателе googlePayTestEnvironment укажите true).
  2. Заполните чек-лист Google Pay, нажмите REQUEST PRODUCTION ACCESS и приложите ссылку на APK с тестовым режимом Google Pay.
  3. Дождитесь ответа от Google.
  4. После успешной проверки уберите тестовый режим Google Pay из приложения.

Платеж через Google Pay

Пример ShopParameters для Google Pay

new ShopParameters(
    "<Название магазина>",
    "<Описание магазина>",
    "<Ключ для клиентских приложений>",
    Collections.emptySet(),
    true, // включает Google Pay
    "123456", // shopId, идентификатор магазина в личном кабинете
    ...
)
  1. Запустите токенизацию (Checkout.tokenize()), в качестве ShopParameters укажите код из примера.
  2. Получите токен.
  3. Создайте платеж с токеном по API Яндекс.Кассы со способом, подтверждение пользователем не нужно.

Тестовый режим

Пример запуска приложения в тестовом режиме

class MyActivity extends android.support.v7.app.AppCompatActivity {

    //other code

    void timeToStartCheckout() {

        Checkout.configureTestMode(
            new Configuration(
                // enableTestMode - включает тестовый режим,
                // completeWithError - токенизация проходит с ошибкой,
                // paymentAuthPassed - пользователь авторизован в кошельке на Яндексе
                // linkedCardsCount - количество тестовых банковских карт
                // googlePayAvailable - можно заплатить с Google Pay
                // googlePayTestEnvironment - включить тестовый режим Google Pay (деньги не списываются)
            )
        );

        Checkout.tokenize(
             this,
             new Amount(new BigDecimal("10.0"), Currency.getInstance("RUB")),
             new ShopParameters(
                 "Название магазина",
                 "Описание магазина",
                 "Токен, полученный в Яндекс.Кассе"
            )
        );
    }
}

Тестовый режим позволяет проверить работу SDK без реальных данных. Для запуска тестового режима необходимо вызвать метод Checkout.configureTestMode() и передать ему объект Configuration. Это необходимо сделать до вызова Checkout.tokenize().