Библиотека позволяет встроить прием платежей в мобильные приложения на iOS и работает как дополнение к API ЮKassa.
В мобильный SDK входят готовые платежные интерфейсы (форма оплаты и всё, что с ней связано).
С помощью SDK можно получать токены для проведения оплаты с банковской карты, через Apple Pay, Сбербанк Онлайн или из кошелька в ЮMoney.
- YooKassa Payments SDK
- Changelog
- Migration guide
- Подключение зависимостей
- Быстрая интеграция
- Доступные способы оплаты
- Настройка способов оплаты
- Описание публичных параметров
- Сканирование банковских карт
- Настройка подтверждения платежа
- Логирование
- Тестовый режим
- Запуск Example
- Кастомизация интерфейса
- Платёж привязанной к магазину картой с дозапросом CVC/CVV
- Лицензия
- Установите CocoaPods версии 1.10.0 или выше.
gem install cocoapods
Официальная документация по установке CocoaPods.
Какие версии CocoaPods есть.
- Создайте файл Podfile
CocoaPods предоставляет команду
pod init
для создания Podfile с настройками по умолчанию.
- Добавьте зависимости в
Podfile
.
ПримерPodfile
из демо-приложения.
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/yoomoney-tech/cocoa-pod-specs.git'
platform :ios, '10.0'
use_frameworks!
target 'Your Target Name' do
pod 'YooKassaPayments',
:git => 'https://github.com/yoomoney/yookassa-payments-swift.git',
:tag => 'tag'
end
Your Target Name
- название таргета в Xcode для вашего приложения.
tag
- версия SDK. Актуальную версию можно узнать на github в разделе releases.
Если вы используете static linkage, то необходимо подключить plugin
cocoapods-user-defined-build-types
:
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/yoomoney-tech/cocoa-pod-specs.git'
plugin 'cocoapods-user-defined-build-types'
enable_user_defined_build_types!
platform :ios, '10.0'
target 'Your Target Name' do
pod 'YooKassaPayments',
:build_type => :dynamic_framework,
:git => 'https://github.com/yoomoney/yookassa-payments-swift.git',
:tag => 'tag'
end
- Выполните команду
pod install
На текущий момент Carthage не поддерживается.
- Создайте
TokenizationModuleInputData
(понадобится ключ для клиентских приложений из личного кабинета ЮKassa). В этой модели передаются параметры платежа (валюта и сумма) и параметры платежной формы, которые увидит пользователь при оплате (способы оплаты, название магазина и описание заказа).
Для работы с сущностями YooKassaPayments импортируйте зависимости в исходный файл
import YooKassaPayments
Пример создания TokenizationModuleInputData
:
let clientApplicationKey = "<Ключ для клиентских приложений>"
let amount = Amount(value: 999.99, currency: .rub)
let tokenizationModuleInputData =
TokenizationModuleInputData(clientApplicationKey: clientApplicationKey,
shopName: "Космические объекты",
purchaseDescription: """
Комета повышенной яркости, период обращения — 112 лет
""",
amount: amount,
savePaymentMethod: .on)
- Создайте
TokenizationFlow
с кейсом.tokenization
и передайтеTokenizationModuleInputData
.
Пример создания TokenizationFlow
:
let inputData: TokenizationFlow = .tokenization(tokenizationModuleInputData)
- Создайте
ViewController
изTokenizationAssembly
и выведите его на экран.
let viewController = TokenizationAssembly.makeModule(inputData: inputData,
moduleOutput: self)
present(viewController, animated: true, completion: nil)
В moduleOutput
необходимо передать объект, который реализует протокол TokenizationModuleOutput
.
- Реализуйте протокол
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: YooKassaPaymentsError?
) {
DispatchQueue.main.async { [weak self] in
guard let self = self else { return }
self.dismiss(animated: true)
}
}
func didSuccessfullyConfirmation(
paymentMethodType: PaymentMethodType
) {
DispatchQueue.main.async { [weak self] in
guard let self = self else { return }
// Создать экран успеха после прохождения подтверждения (3DS или Sberpay)
self.dismiss(animated: true)
// Показать экран успеха
}
}
}
Закройте модуль SDK и отправьте токен в вашу систему. Затем создайте платеж по API ЮKassa, в параметре payment_token
передайте токен, полученный в SDK. Способ подтверждения при создании платежа зависит от способа оплаты, который выбрал пользователь. Он приходит вместе с токеном в paymentMethodType
.
Сейчас в SDK для iOS доступны следующие способы оплаты:
.yooMoney
— ЮMoney (платежи из кошелька или привязанной картой)
.bankCard
— банковская карта (карты можно сканировать)
.sberbank
— SberPay (с подтверждением через приложение Сбербанк Онлайн, если оно установленно, иначе с подтверждением по смс)
.applePay
— Apple Pay
У вас есть возможность сконфигурировать способы оплаты.
Для этого необходимо при создании TokenizationModuleInputData
в параметре tokenizationSettings
передать модель типа TokenizationSettings
.
Для некоторых способов оплаты нужна дополнительная настройка (см. ниже).
По умолчанию используются все доступные способы оплаты.
// Создайте пустой OptionSet PaymentMethodTypes
var paymentMethodTypes: PaymentMethodTypes = []
if <Условие для банковской карты> {
// Добавляем в paymentMethodTypes элемент `.bankCard`
paymentMethodTypes.insert(.bankCard)
}
if <Условие для Сбербанка Онлайн> {
// Добавляем в paymentMethodTypes элемент `.sberbank`
paymentMethodTypes.insert(.sberbank)
}
if <Условие для ЮMoney> {
// Добавляем в paymentMethodTypes элемент `.yooMoney`
paymentMethodTypes.insert(.yooMoney)
}
if <Условие для Apple Pay> {
// Добавляем в paymentMethodTypes элемент `.applePay`
paymentMethodTypes.insert(.applePay)
}
let tokenizationSettings = TokenizationSettings(paymentMethodTypes: paymentMethodTypes)
Теперь используйте tokenizationSettings
при инициализации TokenizationModuleInputData
.
Для подключения способа оплаты ЮMoney
необходимо:
- Получить
client id
центра авторизации системыЮMoney
. - При создании
TokenizationModuleInputData
передатьclient id
в параметреmoneyAuthClientId
- Авторизуйтесь на yookassa.ru
- Перейти на страницу регистрации клиентов СЦА - yookassa.ru/oauth/v2/client
- Нажать Зарегистрировать
- Заполнить поля:
4.1. "Название" -required
поле, отображается при выдаче прав и в списке приложений.
4.2. "Описание" -optional
поле, отображается у пользователя в списке приложений.
4.3. "Ссылка на сайт приложения" -optional
поле, отображается у пользователя в списке приложений.
4.4. "Код подтверждения" - выбратьПередавать в Callback URL
, можно указывать любое значение, например ссылку на сайт. - Выбрать доступы:
5.1.Кошелёк ЮMoney
->Просмотр
5.2.Профиль ЮMoney
->Просмотр
- Нажать
Зарегистрировать
При создании TokenizationModuleInputData
передать client id
в параметре moneyAuthClientId
let moduleData = TokenizationModuleInputData(
...
moneyAuthClientId: "client_id")
Чтобы провести платеж:
- При создании
TokenizationModuleInputData
передайте значение.yooMoney
вpaymentMethodTypes.
- Получите токен.
- Создайте платеж с токеном по API ЮKassa.
- В
TokenizationModuleInputData
необходимо передаватьapplicationScheme
– схема для возврата в приложение после успешной авторизации вЮMoney
через мобильное приложение.
Пример applicationScheme
:
let moduleData = TokenizationModuleInputData(
...
applicationScheme: "examplescheme://"
-
В
AppDelegate
импортировать зависимостьYooKassaPayments
:import YooKassaPayments
-
Добавить обработку ссылок через
YKSdk
вAppDelegate
:
func application(
_ application: UIApplication,
open url: URL,
sourceApplication: String?,
annotation: Any
) -> Bool {
return YKSdk.shared.handleOpen(
url: url,
sourceApplication: sourceApplication
)
}
@available(iOS 9.0, *)
func application(
_ app: UIApplication,
open url: URL,
options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
return YKSdk.shared.handleOpen(
url: url,
sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
)
}
- В
Info.plist
добавьте следующие строки:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>yoomoneyauth</string>
</array>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>${BUNDLE_ID}</string>
<key>CFBundleURLSchemes</key>
<array>
<string>examplescheme</string>
</array>
</dict>
</array>
где examplescheme
- схема для открытия вашего приложения, которую вы указали в applicationScheme
при создании TokenizationModuleInputData
. Через эту схему будет открываться ваше приложение после успешной авторизации в ЮMoney
через мобильное приложение.
- При создании
TokenizationModuleInputData
передайте значение.bankcard
вpaymentMethodTypes
. - Получите токен.
- Создайте платеж с токеном по API ЮKassa.
С помощью SDK можно провести платеж через «Мобильный банк» Сбербанка — с подтверждением оплаты через приложение Сбербанк Онлайн, если оно установленно, иначе с подтверждением по смс.
В TokenizationModuleInputData
необходимо передавать applicationScheme
– схема для возврата в приложение после успешной оплаты с помощью SberPay
в приложении СберБанк Онлайн.
Пример applicationScheme
:
let moduleData = TokenizationModuleInputData(
...
applicationScheme: "examplescheme://"
Чтобы провести платёж:
- При создании
TokenizationModuleInputData
передайте значение.sberbank
вpaymentMethodTypes
. - Получите токен.
- Создайте платеж с токеном по API ЮKassa.
Для подтверждения платежа через приложение СберБанк Онлайн:
-
В
AppDelegate
импортируйте зависимостьYooKassaPayments
:import YooKassaPayments
-
Добавьте обработку ссылок через
YKSdk
вAppDelegate
:
func application(
_ application: UIApplication,
open url: URL,
sourceApplication: String?,
annotation: Any
) -> Bool {
return YKSdk.shared.handleOpen(
url: url,
sourceApplication: sourceApplication
)
}
@available(iOS 9.0, *)
func application(
_ app: UIApplication,
open url: URL,
options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
return YKSdk.shared.handleOpen(
url: url,
sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String
)
}
- В
Info.plist
добавьте следующие строки:
<key>LSApplicationQueriesSchemes</key>
<array>
<string>sberpay</string>
</array>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>${BUNDLE_ID}</string>
<key>CFBundleURLSchemes</key>
<array>
<string>examplescheme</string>
</array>
</dict>
</array>
где examplescheme
- схема для открытия вашего приложения, которую вы указали в applicationScheme
при создании TokenizationModuleInputData
. Через эту схему будет открываться ваше приложение после успешной оплаты с помощью SberPay
.
- Реализуйте метод
didSuccessfullyConfirmation(paymentMethodType:)
протоколаTokenizationModuleOutput
, который будет вызван после успешного подтверждения платежа (см. Настройка подтверждения платежа).
- Чтобы подключить Apple Pay, нужно передать в ЮKassa сертификат, с помощью которого Apple будет шифровать данные банковских карт.
Для этого:
- Напишите менеджеру и попросите создать для вас запрос на сертификат (
.csr
). - Создайте сертификат в панели разработчика Apple (используйте
.csr
). - Скачайте получившийся сертификат и пришлите менеджеру.
Подробная инструкция (см. раздел 2 «Обмен сертификатами с Apple»)
- Включите Apple Pay в Xcode.
Чтобы провести платеж:
- При инициализации объекта
TokenizationModuleInputData
необходимо передать apple pay identifier в параметрapplePayMerchantIdentifier
.
let moduleData = TokenizationModuleInputData(
...
applePayMerchantIdentifier: "com.example.identifier"
- Получите токен.
- Создайте платеж с токеном по API ЮKassa.
Enum
, который определяет логику работы SDK.
Case | Тип | Описание |
---|---|---|
tokenization | TokenizationFlow | Принимает на вход модель TokenizationModuleInputData . Логика для токенизации несколько способов оплаты на выбор: Банковская карта, ЮMoney, Сбербанк-Онлайн, Apple Pay |
bankCardRepeat | TokenizationFlow | Принимает на вход модель BankCardRepeatModuleInputData . Логика для токенизации сохраненных способов оплаты по идентификатору способа оплаты |
Enum
с возможными ошибками, которые можно обработать в методе func didFinish(on module:, with error:)
Case | Тип | Описание |
---|---|---|
paymentMethodNotFound | Error | По paymentMethodId не было найдено ни одного сохраненного способа оплаты. |
Обязательные:
Параметр | Тип | Описание |
---|---|---|
clientApplicationKey | String | Ключ для клиентских приложений из личного кабинета ЮKassa |
shopName | String | Название магазина в форме оплаты |
purchaseDescription | String | Описание заказа в форме оплаты |
amount | Amount | Объект, содержащий сумму заказа и валюту |
savePaymentMethod | SavePaymentMethod | Объект, описывающий логику того, будет ли платеж рекуррентным |
Необязательные:
Параметр | Тип | Описание |
---|---|---|
gatewayId | String | По умолчанию nil . Используется, если у вас несколько платежных шлюзов с разными идентификаторами. |
tokenizationSettings | TokenizationSettings | По умолчанию используется стандартный инициализатор со всеми способами оплаты. Параметр отвечает за настройку токенизации (способы оплаты и логотип ЮKassa). |
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. Если вы используете startConfirmationProcess(confirmationUrl:paymentMethodType:) , не задавайте этот параметр. |
isLoggingEnabled | Bool | По умолчанию false . Включает логирование сетевых запросов. |
userPhoneNumber | String | По умолчанию nil . Телефонный номер пользователя. |
customizationSettings | CustomizationSettings | По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода. |
moneyAuthClientId | String | По умолчанию nil . Идентификатор для центра авторизации в системе YooMoney. |
applicationScheme | String | По умолчанию nil . Схема для возврата в приложение после успешной оплаты с помощью Sberpay в приложении СберБанк Онлайн или после успешной авторизации в YooMoney через мобильное приложение. |
customerId | String | По умолчанию nil . Уникальный идентификатор покупателя в вашей системе, например электронная почта или номер телефона. Не более 200 символов. Используется, если вы хотите запомнить банковскую карту и отобразить ее при повторном платеже в mSdk. Убедитесь, что customerId относится к пользователю, который хочет совершить покупку. Например, используйте двухфакторную аутентификацию. Если передать неверный идентификатор, пользователь сможет выбрать для оплаты чужие банковские карты. |
Обязательные:
Параметр | Тип | Описание |
---|---|---|
clientApplicationKey | String | Ключ для клиентских приложений из личного кабинета ЮKassa |
shopName | String | Название магазина в форме оплаты |
purchaseDescription | String | Описание заказа в форме оплаты |
paymentMethodId | String | Идентификатор сохраненного способа оплаты |
amount | Amount | Объект, содержащий сумму заказа и валюту |
savePaymentMethod | SavePaymentMethod | Объект, описывающий логику того, будет ли платеж рекуррентным |
Необязательные:
Параметр | Тип | Описание |
---|---|---|
testModeSettings | TestModeSettings | По умолчанию nil . Настройки тестового режима. |
returnUrl | String | По умолчанию nil . URL страницы (поддерживается только https ), на которую надо вернуться после прохождения 3-D Secure. Необходим только при кастомной реализации 3-D Secure. Если вы используете startConfirmationProcess(confirmationUrl:paymentMethodType:) , не задавайте этот параметр. |
isLoggingEnabled | Bool | По умолчанию false . Включает логирование сетевых запросов. |
customizationSettings | CustomizationSettings | По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода. |
gatewayId | String | По умолчанию nil . Используется, если у вас несколько платежных шлюзов с разными идентификаторами. |
Можно настроить список способов оплаты и отображение логотипа ЮKassa в приложении.
Параметр | Тип | Описание |
---|---|---|
paymentMethodTypes | PaymentMethodTypes | По умолчанию .all . Способы оплаты, доступные пользователю в приложении. |
showYooKassaLogo | Bool | По умолчанию true . Отвечает за отображение логотипа ЮKassa. По умолчанию логотип отображается. |
Параметр | Тип | Описание |
---|---|---|
paymentAuthorizationPassed | Bool | Определяет, пройдена ли платежная авторизация при оплате ЮMoney. |
cardsCount | Int | Количество привязанные карт к кошельку в ЮMoney. |
charge | Amount | Сумма и валюта платежа. |
enablePaymentError | Bool | Определяет, будет ли платеж завершен с ошибкой. |
Параметр | Тип | Описание |
---|---|---|
value | Decimal | Сумма платежа |
currency | Currency | Валюта платежа |
Параметр | Тип | Описание |
---|---|---|
rub | String | ₽ - Российский рубль |
usd | String | $ - Американский доллар |
eur | String | € - Евро |
custom | String | Будет отображаться значение, которое передали |
Параметр | Тип | Описание |
---|---|---|
mainScheme | UIColor | По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода. |
Параметр | Тип | Описание |
---|---|---|
on | SavePaymentMethod | Сохранить платёжный метод для проведения рекуррентных платежей. Пользователю будут доступны только способы оплаты, поддерживающие сохранение. На экране контракта будет отображено сообщение о том, что платёжный метод будет сохранён. |
off | SavePaymentMethod | Не дает пользователю выбрать, сохранять способ оплаты или нет. |
userSelects | SavePaymentMethod | Пользователь выбирает, сохранять платёжный метод или нет. Если метод можно сохранить, на экране контракта появится переключатель. |
Если хотите, чтобы пользователи смогли сканировать банковские карты при оплате, необходимо:
- Создать сущность и реализовать протокол
CardScanning
.
class CardScannerProvider: CardScanning {
weak var cardScanningDelegate: CardScanningDelegate?
var cardScanningViewController: UIViewController? {
// Create and return scanner view controller
viewController.delegate = self
return viewController
}
}
- Настроить получение данных из вашего инструмента для сканирования банковской карты.
На примере 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)
}
}
- Передать экземпляр объекта
CardScannerProvider
вTokenizationModuleInputData
в параметрcardScanning:
.
let inputData = TokenizationModuleInputData(
...
cardScanning: CardScannerProvider())
Если вы хотите использовать нашу реализацию подтверждения платежа, не закрывайте модуль SDK после получения токена.
Отправьте токен на ваш сервер и после успешной оплаты закройте модуль.
Если ваш сервер сообщил о необходимости подтверждения платежа (т.е. платёж пришёл со статусом pending
), вызовите метод startConfirmationProcess(confirmationUrl:paymentMethodType:)
.
После успешного прохождения подтверждения будет вызван метод didSuccessfullyConfirmation(paymentMethodType:)
протокола TokenizationModuleOutput
.
Примеры кода:
- Сохраните tokenization модуль.
self.tokenizationViewController = TokenizationAssembly.makeModule(inputData: inputData,
moduleOutput: self)
present(self.tokenizationViewController, animated: true, completion: nil)
- Не закрывайте tokenization модуль после получения токена.
func tokenizationModule(_ module: TokenizationModuleInput,
didTokenize token: Tokens,
paymentMethodType: PaymentMethodType) {
// Отправьте токен на ваш сервер.
}
- Вызовите подтверждение платежа, если это необходимо.
self.tokenizationViewController.startConfirmationProcess(
confirmationUrl: confirmationUrl,
paymentMethodType: paymentMethodType
)
- После успешного подтверждения платежа будет вызван метод.
func didSuccessfullyConfirmation(paymentMethodType: PaymentMethodType) {
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 в тестовом режиме, необходимо:
- Сконфигурировать объект с типом
TestModeSettings
.
let testModeSettings = TestModeSettings(paymentAuthorizationPassed: false,
cardsCount: 2,
charge: Amount(value: 999, currency: .rub),
enablePaymentError: false)
- Передать его в
TokenizationModuleInputData
в параметреtestModeSettings:
let moduleData = TokenizationModuleInputData(
...
testModeSettings: testModeSettings)
Чтобы запустить Example приложение, необходимо:
- Сделать
git clone
репозитория.
git clone https://github.com/yoomoney/yookassa-payments-swift.git
- В консоли перейти в папку с проектом и выполнить следующие команды:
gem install bundler
bundle
pod install
- Открыть
YooKassaPayments.xcworkspace
. - Выбрать и запустить схему
YooKassaPaymentsDemoApp
.
По умолчанию используется цвет blueRibbon. Цвет основных элементов, кнопки, переключатели, поля ввода.
- Сконфигурировать объект
CustomizationSettings
и передать его в параметрcustomizationSettings
объектаTokenizationModuleInputData
.
let moduleData = TokenizationModuleInputData(
...
customizationSettings: CustomizationSettings(mainScheme: /* UIColor */ ))
- Создайте
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)
)
- Создайте
TokenizationFlow
с кейсом.bankCardRepeat
и передайтеBankCardRepeatModuleInputData
.
let inputData: TokenizationFlow = .bankCardRepeat(bankCardRepeatModuleInputData)
- Создайте
ViewController
изTokenizationAssembly
и выведите его на экран.
let viewController = TokenizationAssembly.makeModule(
inputData: inputData,
moduleOutput: self
)
present(viewController, animated: true, completion: nil)
YooKassa Payments SDK доступна под лицензией MIT. Смотрите LICENSE файл для получения дополнительной информации.