Yandex Checkout Payments SDK

Библиотека позволяет встроить прием платежей в мобильные приложения на iOS и работает как дополнение к API Яндекс.Кассы.
В мобильный SDK входят готовые платежные интерфейсы (форма оплаты и всё, что с ней связано).
С помощью SDK можно получать токены для проведения оплаты с банковской карты, через Apple Pay, Сбербанк Онлайн или из кошелька в Яндекс.Деньгах.

• Код библиотеки
• Код демо-приложения, которое интегрирует SDK
• Документация

---

• Yandex Checkout Payments SDK
  • Changelog
  • Migration guide
  • Подключение зависимостей
    • CocoaPods
    • Carthage
  • Подключение TrustDefender
  • Быстрая интеграция
  • Доступные способы оплаты
  • Настройка способов оплаты
    • Яндекс Деньги
    • Банковская карта
    • Сбербанк Онлайн
    • Apple Pay
  • Описание публичных параметров
    • TokenizationFlow
    • YandexCheckoutPaymentsError
    • TokenizationModuleInputData
    • BankCardRepeatModuleInputData
    • TokenizationSettings
    • TestModeSettings
    • Amount
    • Currency
    • CustomizationSettings
    • SavePaymentMethod
  • Сканирование банковских карт
  • Настройка 3D Secure
  • Логирование
  • Тестовый режим
  • Запуск Example
  • Кастомизация интерфейса
  • Платёж привязанной к магазину картой с дозапросом CVC/CVV

Changelog

Ссылка на Changelog

Migration guide

Ссылка на Migration guide

Подключение зависимостей

CocoaPods

1. Установите CocoaPods

gem install cocoapods

2. Создайте файл Podfile\

CocoaPods предоставляет команду pod init для создания Podfile с настройками по умолчанию.

3. Добавьте зависимости в Podfile.
   Пример 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

Your Target Name - название таргета в Xcode для вашего приложения.
tag - версия SDK. Актуальную версию можно узнать на github в разделе releases.

4. Выполните команду pod install

Carthage

На текущий момент Carthage не поддерживается.

Подключение TrustDefender

Чтобы получить файл .framework, зарегистрируйтесь в Яндекс.Кассе и сообщите вашему менеджеру, что хотите подключить мобильный SDK.

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

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

Если в проекте отсутствует папка Frameworks создайте её вручную.

2. Если во время запуска проекта вы видите ошибку dyld: Library not loaded: @rpath/TrustDefender.framework/TrustDefender, в разделе General у основного таргета проекта добавьте TrustDefender.framework в Embedded Binaries(в Xcode 10.3 или меньше), или в Frameworks, Libraries, and Embedded Content(в Xcode 11)

3. Добавьте в Build Phases -> New Run Script Phase, и добавьте скрипт из файла strip_framework.sh

4. Если во время сборки проекта вы видите сообщение с ошибкой о TrustDefender.framework/TrustDefender' does not contain bitcode, необходимо выключить bitcode в разделе Build Settings у основного таргета проекта.

Быстрая интеграция

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

Для работы с сущностями YandexCheckoutPayments импортируйте зависимости в исходный файл

import YandexCheckoutPayments
import YandexCheckoutPaymentsApi

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

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

2. Создайте TokenizationFlow с кейсом .tokenization и передайте TokenizationModuleInputData.

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

let inputData: TokenizationFlow = .tokenization(tokenizationModuleInputData)

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

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

В moduleOutput необходимо передать объект, который реализует протокол TokenizationModuleOutput.

4. Реализуйте протокол TokenizationModuleOutput.

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

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

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

Доступные способы оплаты

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

.yandexMoney — Яндекс.Деньги (платежи из кошелька или привязанной картой)
.bankCard — банковская карта (карты можно сканировать)
.sberbank — Сбербанк Онлайн (с подтверждением по смс)
.applePay — Apple Pay

Настройка способов оплаты

У вас есть возможность сконфигурировать способы оплаты.
Для этого необходимо при создании TokenizationModuleInputData в параметре tokenizationSettings передать модель типа 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)
}

let tokenizationSettings = TokenizationSettings(paymentMethodTypes: paymentMethodTypes)

Теперь используйте tokenizationSettings при инициализации TokenizationModuleInputData.

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

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

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

   • Введите название приложения.
   • В разделе API Яндекс.Паспорта необходимо выбрать Доступ к логину, имени и фамилии, полу

2. Добавьте в Info.plist следующие строки:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>yandexauth</string>
    <string>yandexauth2</string>
</array>
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>YandexLoginSDK</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yx<ID из Яндекс.OAuth></string>
        </array>
    </dict>
</array>

3. Настройте Entitlements

В своем проекте в разделе Capabilities включите Associated Domains и добавьте домен по шаблону:

applinks:yx<ID из Яндекс.OAuth>.oauth.yandex.ru.

Например, если ваш ID из Яндекс.OAuth — 333, домен будет таким:

applinks:yx333.oauth.yandex.ru.

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

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

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

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

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

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

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

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

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

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

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

Apple Pay

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

Для этого:

• Напишите менеджеру и попросите создать для вас запрос на сертификат (.csr).
• Создайте сертификат в панели разработчика Apple (используйте .csr).
• Скачайте получившийся сертификат и пришлите менеджеру.

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

2. Включите Apple Pay в Xcode.

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

1. При инициализации объекта TokenizationModuleInputData необходимо передать apple pay identifier в параметр applePayMerchantIdentifier.

let moduleData = TokenizationModuleInputData(
    ...
    applePayMerchantIdentifier: "<com.example...>")

Например, если ваш apple pay identifier — com.example.identifier, то код будет следующим:

let moduleData = TokenizationModuleInputData(
    ...
    applePayMerchantIdentifier: "com.example.identifier")

2. Получите токен.
3. Создайте платеж с токеном по API Яндекс.Кассы.

Описание публичных параметров

TokenizationFlow

Enum, который определяет логику работы SDK.

Case	Тип	Описание
tokenization	TokenizationFlow	Принимает на вход модель TokenizationModuleInputData. Логика для токенизации несколько способов оплаты на выбор: Банковская карта, Яндекс Деньги, Сбербанк-Онлайн, Apple Pay
bankCardRepeat	TokenizationFlow	Принимает на вход модель BankCardRepeatModuleInputData. Логика для токенизации сохраненных способов оплаты по идентификатору способа оплаты

YandexCheckoutPaymentsError

Enum с возможными ошибками, которые можно обработать в методе func didFinish(on module:, with error:)

Case	Тип	Описание
paymentMethodNotFound	Error	По paymentMethodId не было найдено ни одного сохраненного способа оплаты.

TokenizationModuleInputData

Обязательные:

Параметр	Тип	Описание
clientApplicationKey	String	Ключ для клиентских приложений из личного кабинета Яндекс.Кассы
shopName	String	Название магазина в форме оплаты
purchaseDescription	String	Описание заказа в форме оплаты
amount	Amount	Объект, содержащий сумму заказа и валюту

|

Необязательные:

Параметр	Тип	Описание
gatewayId	String	По умолчанию nil. Используется, если у вас несколько платежных шлюзов с разными идентификаторами.
tokenizationSettings	TokenizationSettings	По умолчанию используется стандартный инициализатор со всеми способами оплаты. Параметр отвечает за настройку токенизации (способы оплаты и логотип Яндекс.Кассы).
testModeSettings	TestModeSettings	По умолчанию nil. Настройки тестового режима.
cardScanning	CardScanning	По умолчанию nil. Возможность сканировать банковские карты.
applePayMerchantIdentifier	String	По умолчанию nil. Apple Pay merchant ID (обязательно для платежей через Apple Pay).
returnUrl	String	По умолчанию nil. URL страницы (поддерживается только https), на которую надо вернуться после прохождения 3-D Secure. Необходим только при кастомной реализации 3-D Secure. Если вы используете start3dsProcess(requestUrl:), не задавайте этот параметр.
isLoggingEnabled	Bool	По умолчанию false. Включает логирование сетевых запросов.
userPhoneNumber	String	По умолчанию nil. Телефонный номер пользователя.
customizationSettings	CustomizationSettings	По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.

BankCardRepeatModuleInputData

Обязательные:

Параметр	Тип	Описание
clientApplicationKey	String	Ключ для клиентских приложений из личного кабинета Яндекс.Кассы
shopName	String	Название магазина в форме оплаты
purchaseDescription	String	Описание заказа в форме оплаты
paymentMethodId	String	Идентификатор сохраненного способа оплаты
amount	Amount	Объект, содержащий сумму заказа и валюту

Необязательные:

Параметр	Тип	Описание
testModeSettings	TestModeSettings	По умолчанию nil. Настройки тестового режима.
returnUrl	String	По умолчанию nil. URL страницы (поддерживается только https), на которую надо вернуться после прохождения 3-D Secure. Необходим только при кастомной реализации 3-D Secure. Если вы используете start3dsProcess(requestUrl:), не задавайте этот параметр.
isLoggingEnabled	Bool	По умолчанию false. Включает логирование сетевых запросов.
customizationSettings	CustomizationSettings	По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.

TokenizationSettings

Можно настроить список способов оплаты и отображение логотипа Яндекс.Кассы в приложении.

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

TestModeSettings

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

Amount

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

Currency

Параметр	Тип	Описание
rub	String	₽ - Российский рубль
usd	String	$ - Американский доллар
eur	String	€ - Евро

CustomizationSettings

Параметр	Тип	Описание
mainScheme	UIColor	По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.

SavePaymentMethod

Параметр	Тип	Описание
on	SavePaymentMethod	Сохранить платёжный метод для проведения рекуррентных платежей. Пользователю будут доступны только способы оплаты, поддерживающие сохранение. На экране контракта будет отображено сообщение о том, что платёжный метод будет сохранён.
off	SavePaymentMethod	Не сохранять платёжный метод.
userSelects	SavePaymentMethod	Пользователь выбирает, сохранять платёжный метод или нет. Если метод можно сохранить, на экране контракта появится переключатель.

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

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

1. Создать сущность и реализовать протокол CardScanning.

class CardScannerProvider: CardScanning {
    weak var cardScanningDelegate: CardScanningDelegate?

    var cardScanningViewController: UIViewController? {

        // Create and return scanner view controller

        viewController.delegate = self
        return viewController
    }
}

2. Настроить получение данных из вашего инструмента для сканирования банковской карты.
   На примере CardIO:

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)
    }
}

3. Передать экземпляр объекта CardScannerProvider в TokenizationModuleInputData в параметр cardScanning:.

let inputData = TokenizationModuleInputData(
    ...
    cardScanning: CardScannerProvider())

Настройка 3D Secure

Если вы хотите использовать нашу реализацию 3-D Secure, не закрывайте модуль SDK после получения токена.
Отправьте токен на ваш сервер и после успешной оплаты закройте модуль.
Если ваш сервер сообщил о необходимости подтверждения платежа (т.е. платёж пришёл со статусом pending), вызовите метод start3dsProcess(requestUrl:)

После успешного прохождения 3-D Secure будет вызван метод didSuccessfullyPassedCardSec(on module:) протокола TokenizationModuleOutput.

Примеры кода:

1. Сохраните tokenization модуль.

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

2. Не закрывайте tokenization модуль после получения токена.

func tokenizationModule(_ module: TokenizationModuleInput,
                        didTokenize token: Tokens,
                        paymentMethodType: PaymentMethodType) {
    // Отправьте токен на ваш сервер.
}

3. Покажите 3-D Secure, если необходимо подтвердить платеж.

func needsConfirmPayment(requestUrl: String) {
    self.tokenizationViewController.start3dsProcess(requestUrl: requestUrl)
}

4. После успешного прохождения 3-D Secure будет вызван метод.

func didSuccessfullyPassedCardSec(on module: TokenizationModuleInput) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }

        // Now close tokenization module
        self.dismiss(animated: true)
    }
}

Логирование

У вас есть возможность включить логирование всех сетевых запросов.
Для этого необходимо при создании TokenizationModuleInputData передать isLoggingEnabled: true

let moduleData = TokenizationModuleInputData(
    ...
    isLoggingEnabled: true)

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

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

Если вы хотите запустить SDK в тестовом режиме, необходимо:

1. Сконфигурировать объект с типом TestModeSettings.

let testModeSettings = TestModeSettings(paymentAuthorizationPassed: false,
                                        cardsCount: 2,
                                        charge: Amount(value: 999, currency: .rub),
                                        enablePaymentError: false)

2. Передать его в TokenizationModuleInputData в параметре testModeSettings:

let moduleData = TokenizationModuleInputData(
    ...
    testModeSettings: testModeSettings)

Запуск Example

Чтобы запустить Example приложение, необходимо:

1. Сделать git clone репозитория.

git clone https://github.com/yandex-money/yandex-checkout-payments-swift.git

2. Добавить TrustDefender.framework в папку Frameworks, которая находится на одном уровне с папкой Pods (см. Подключение TrustDefender)
3. В консоли перейти в папку с проектом и выполнить следующие команды:

gem install bundler
bundle
pod install

4. Открыть YandexCheckoutPayments.xcworkspace.
5. Выбрать и запустить схему ExamplePods.

Кастомизация интерфейса

По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.

1. Сконфигурировать объект CustomizationSettings и передать его в параметр customizationSettings объекта TokenizationModuleInputData.

let moduleData = TokenizationModuleInputData(
    ...
    customizationSettings: CustomizationSettings(mainScheme: /* UIColor */ ))

Платёж привязанной к магазину картой с дозапросом CVC/CVV

1. Создайте BankCardRepeatModuleInputData.

let bankCardRepeatModuleInputData = BankCardRepeatModuleInputData(
            clientApplicationKey: oauthToken,
            shopName: translate(Localized.name),
            purchaseDescription: translate(Localized.description),
            paymentMethodId: "24e4eca6-000f-5000-9000-10a7bb3cfdb2",
            amount: amount,
            testModeSettings: testSettings,
            isLoggingEnabled: true,
            customizationSettings: CustomizationSettings(mainScheme: .blueRibbon)
        )

2. Создайте TokenizationFlow с кейсом .bankCardRepeat и передайте BankCardRepeatModuleInputData.

let inputData: TokenizationFlow = .bankCardRepeat(bankCardRepeatModuleInputData)

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

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

Лицензия

Yandex Checkout Payments SDK доступна под лицензией MIT. Смотрите LICENSE файл для получения дополнительной информации.