SDK для iOS: UI & Core

Общая информация

Введение

SDK для iOS: UI & Core — это набор средств разработки с открытым программным кодом, который может использоваться для подключения к платежной платформе JetPay мобильных приложений, работающих на платформе iOS.

SDK для iOS: UI & Core позволяет обеспечивать взаимодействие мобильного приложения с платежной платформой для отправки и приема необходимой информации при проведении платежей, а также обеспечивает интерфейсное взаимодействие с пользователями. Кроме того, за счет открытого программного кода при использовании SDK для iOS: UI & Core можно гибко настраивать пользовательский интерфейс, адаптируя его под специфику приложения.

SDK для iOS: UI & Core можно встраивать в мобильные приложения, работающие на платформе iOS версии 14 и выше. Библиотеки SDK для iOS: UI & Core и примеры кода расположены на портале GitHub. Для работы с ними можно использовать следующие ссылки:

Верси SDK для iOS: UI & Core — https://github.com/Jetpay/msdk-ios-ui/releases
Примеры кода — https://github.com/Jetpay/msdk-ios-ui

В этой статье представлена информация о работе с SDK для iOS: UI & Core с примерами кода на языках Swift и Objective-C.

Возможности

SDK для iOS: UI & Core предоставляет следующие возможности:

Проведение платежей различных типов с прямым использованием платежных карт и с применением метода Apple Pay, а также других платежных методов, доступных проекте мерчанта. Поддерживаются следущие платежи:
- одностадийная разовая оплата;
- двухстадийная разовая оплата с блокировкой средств через SDK и последующим списанием через Gate или Dashboard;
- повторяемые оплаты с регистрацией через SDK и последующим управлением списаниями через Gate или Dashboard.
Прим.: Платежи с использованием карт и метода Apple Pay выполняются с помощью описанного в этом разделе платежного интерфейса, а в других платежных методах используется платежная форма Payment Page.
Проверка платежных карт (с проведением условного платежа на нулевую сумму).
Контроль состояния платежей.
Поддержка различных вспомогательных процедур и дополнительных возможностей для повышения проходимости платежей, в том числе:
- дополнение информации о платежах;
- повторные попытки проведения платежей;
- каскадное проведение платежей;
- сбор данных о пользователях.
Поддержка различных дополнительных возможностей для улучшения пользовательского опыта, включая:
- сохранение платежных данных пользователей;
- управление языком платежного интерфейса;
- отправку пользователям уведомлений с информацией о товарных позициях по проведенным платежам.
Возможности индивидуального оформления платежного интерфейса, включая его стилизацию за счет использования логотипа и настройки цветовой палитры, а также более глубокую адаптацию к специфике приложения за счет работы с открытым программным кодом SDK.

Схема работы

В общем случае одностадийная оплата с использованием SDK для iOS: UI & Core проводятся в соответствии со следующей схемой.

Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом.
В приложении формируется набор параметров для создания платежной сессии, с помощью SDK для iOS: UI & Core этот набор преобразуется в строку для подписывания, после чего строка передается к серверной части веб-сервиса мерчанта.
В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK для iOS: UI & Core.
С помощью SDK для iOS: UI & Core инициируется создание платежной сессии в платежной платформе.
На стороне платежной платформы выполняются подготовка платежного интерфейса с учетом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса.
В мобильном приложении пользователю отображается форма оплаты.
Пользователь выбирает платежный метод (если он не был задан при открытии платежной сессии), указывает необходимую информацию и подтверждает готовность провести оплату.
От SDK для iOS: UI & Core к платежной платформе отправляется запрос на проведение оплаты.
На стороне платежной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платежную среду: к провайдерам и платежным системам.
В платежной среде выполняется обработка платежа, по итогам которой в платежную платформу поступает информация о результате.
В платежной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты.
От платежной платформы к SDK для iOS: UI & Core направляется информация о результате оплаты.
Информация о результате отображается в пользовательском интерфейсе.

Интерфейс

При проведении платежей с использованием платежных карт и альтернативного метода Apple Pay пользователю отображается интерфейс, разработанный специалистами JetPay. Но при желании вы можете изменить базовый цвет пользовательского интерфейса и добавить свой логотип.

Подготовка к использованию

Порядок интеграции

Чтобы подключить свой веб-сервис к платежной платформе JetPay с использованием SDK для iOS: UI & Core:

Решите организационные вопросы, касающиеся взаимодействия с JetPay:
1. Если у вас нет идентификатора и ключа для взаимодействия с JetPay — отправьте заявку на подключение.
2. Если у вас есть идентификатор и ключ для взаимодействия с JetPay, сообщите специалистам технической поддержки о намерении интеграции с использованием SDK для iOS: UI & Core и согласуйте порядок тестирования и запуска.
Выполните подготовительные технические работы:
1. Загрузите и подключите библиотеки SDK для iOS: UI & Core.
2. Обеспечьте сбор данных, необходимых для вызова платежной формы. Для вызова платежной формы как минимум необходимы: идентификаторы проекта, платежа и пользователя, а также сумма и валюта платежа.
3. Обеспечьте подписывание данных в серверной части своего мобильного приложения.
4. Позаботьтесь, чтобы ваш веб-сервис принимал и корректно реагировал на уведомления от SDK для iOS: UI & Core, а также на оповещения от платежной платформы.
Согласуйте со специалистами технической поддержки JetPay порядок и сроки интеграции, тестирования (в том числе с использованием доступных платежных методов) и запуска решения в работу.
1. В процессе тестирования используйте идентификатор тестового проекта и данные тестовых карт.
2. Чтобы перейти в рабочий режим, замените тестовый идентификатор на рабочий идентификатор, полученный от JetPay.

По любым вопросам о работе с SDK для iOS: UI & Core обращайтесь в службу технической поддержки JetPay (support@jetpay.kz).

Подключение библиотек в Swift

Для подключения библиотек к проекту мобильного приложения необходимо:

Перенесите файл jetpaySDK.xcframework в папку проекта мобильного приложения.
Добавьте библиотеку в проект. В Xcode версии 12 для этого необходимо:
1. Откройте цель (target) проекта.
2. Перейдите в General > Embedded Binaries.
3. Щелкните +.
4. Щелкните Add Other.
5. Выберите файл jetpaySDK.xcframework.
6. Щелкните Add.
Добавьте ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через ее сканирование.
Если в мобильном приложении не используется запрос местоположения пользователя, добавьте ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

JetPay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.

Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.
Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, добавьте ключи Privacy - Photo Library Usage Description и Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Значения этих ключей отображаются пользователю при запросе разрешения на сохранение данных.

Подключение библиотек в Objective-C

Чтобы подключить библиотеку к проекту мобильного приложения:

Перенесите файл jetpaySDK.xcframework в папку проекта мобильного приложения.
Добавьте библиотеку к проекту. В Xcode версии 12 для этого сделайте следующее:
1. Откройте цель (target) проекта.
2. Перейдите в General > Embedded Binaries.
3. Щелкните +.
4. Щелкните Add Other.
5. Выберите файл jetpaySDK.xcframework.
6. Щелкните Add.
7. Выберите раздел Build Settings.
8. Установите переключатель Always embed swift embedded libraries в положение Yes.
Добавьте ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты путем ее сканирования.
Если в мобильном приложении не используется запрос местоположения пользователя, добавьте ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

JetPay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.

Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.
Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, добавьте ключи Privacy - Photo Library Usage Description и Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Значения этих ключей отображаются пользователю при запросе разрешения на сохранение данных.

Подключение библиотек через CocoaPods

Для приложений, работающих на платформе iOS 14 и выше можно подключать библиотеку SDK для iOS: UI & Core через CocoaPods. Чтобы подключить библиотеку:

Откройте файл Podfile и добавьте в него следующие строки:
```
target 'App' do
  # Pods for App
  pod 'JetPaySDK_UI', '2.0.0'
end
```
Добавьте ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через ее сканирование.
Если в мобильном приложении не используется запрос местоположения пользователя, добавьте ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

JetPay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым.

Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.
Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, добавьте ключ Privacy - Photo Library Usage Description и ключ Privacy - Photo Library Additions Usage Description с необходимыми значениями в файл Info.plist. Значения этих ключей отображаются пользователю при запросе разрешения на сохранение данных.

Работа с подписью

Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от JetPay. Для работы с подписью можно использовать готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования (подробнее), либо собственные решения, реализованные мерчантом. Порядок работы с подписью представлен в разделе Подписывание и проверка подписи.

Тестирование

При необходимости платежную форму можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок — протестировать проведение оплат с определенным результатом. Для этого в запросе на открытие платежной формы в объекте PaymentOptions можно передать следующие значения для параметра mockModeType (значения указаны для языков Swift и Objective-C соответственно):

MockModeType.success / MockModeTypeSuccess — если необходим результат «платеж проведен»;
MockModeType.decline / MockModeTypeDecline — если необходим результат «платеж отклонен».

Если необходимо открыть платежную форму в рабочем режиме, в параметре mockModeType следует передать значение MockModeType.disabled / MockModeTypeDisabled.

Также проведение платежей можно протестировать в тестовой среде платежной платформы JetPay. Для этого подключитесь к тестовой среде JetPay и укажите полученные идентификатор тестового проекта и соответствующий ему секретный ключ в значении обязательных параметров запроса на открытие платежной формы.

В исходных примерах кода, предоставленных на Github, заданы постоянные значения для этих параметров.

Рис.: Swift

 let secret = "your_secret" // секретный ключ для тестового проекта
    let project_id: Int32 = 10 // идентификатор тестового проекта

Рис.: Objective-C

#define SECRET @"your_secret" // секретный ключ для тестового проекта
#define PROJECT_ID 10 // идентификатор тестового проекта

Если вы готовы перейти в рабочий режим, замените тестовые значения — идентификатор рабочего проекта и секретный ключ от него — на рабочие.

Использование

Вызов платежной формы

SDK для iOS: UI & Core поддерживает проведение одностадийных разовых оплат, блокировку средств пользователей в рамках двухстадийных оплат, регистрацию повторяемых оплат и проверку платежных карт. Для выполения таких действий требуется определенный набор параметров: обязательный минимум передается в объекте PaymentOptions, а остальные параметры можно передать в этом же объекте, запросить их у пользователя или получить от платежной платформы.

Вызов в Swift

Чтобы вызвать платежную форму:

Импортируйте библиотеку.
```
import JetPaySDK
```
Объявите библиотеку JetPaySDK в любом месте приложения (например, внутри метода viewDidLoad).
```
let JetPaySDK = JetPaySDK()
```
Создайте объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платежной формы:
- projectId (integer) — идентификатор проекта, полученный от JetPay;
- paymentId (string) — идентификатор платежа, уникальный в рамках проекта;
- paymentCurrency (string) — код валюты платежа в формате ISO-4217 alpha-3;
- paymentAmount (integer) — сумма платежа в дробных единицах валюты;
- customerId (string) — идентификатор пользователя в рамках проекта;
Чтобы задать нужное действие, укажите тип операции — Sale, Auth или Verify в параметре action. Дополнительно можно использовать и другие параметры, представленные в разделе Параметры вызова.

Вот пример объекта PaymentOptions, который содержит необязательные параметры (описание платежа и страну пользователя):
```
let paymentOptions = PaymentOptions(projectID: 10,
                            paymentID: "internal_payment_id_1",
                            paymentAmount: 1999,
                            paymentCurrency: "USD",
                            paymentDescription: "T-shirt with dog print",
                            customerID: "10",
                            regionCode: "US")
```
Получите строку для подписывания указанных параметров.
```
paymentOptions.paramsForSignature();
```
Передайте сгенерированную строку в серверную часть приложения.
Сгенерируйте подпись на стороне серверной части приложения и передать ее в клиентскую часть.
Добавьте подпись в объект PaymentOptions.
```
paymentOptions.signature = signature;
```
Вызовите платежную форму.
```
JetPaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("JetPaySDK finished with status \(result.status.rawValue)")
   ...
 }
```
После вызова платежной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платежная форма, в других случаях платежная форма не открывается, а метод вызова платежной формы возвращает код ошибки.

Вызов в Objective-C

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

Импортируйте библиотеку:
```
#import <JetPaySDK/JetPaySDK.h>
```
Объявите библиотеку JetPaySDK в любом месте приложения, например внутри метода viewDidLoad.
```
JetPaySDK *self.JetPaySDK = [[JetPaySDK alloc] init];
```
Создайте объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платежной формы:
- projectId (integer) — идентификатор проекта, полученный от JetPay;
- paymentId (string) — идентификатор платежа, уникальный в рамках проекта;
- paymentCurrency (string) — код валюты платежа в формате ISO-4217 alpha-3;
- paymentAmount (integer) — сумма платежа в дробных единицах валюты;
- customerId (string) — идентификатор пользователя в рамках проекта;
Чтобы задать целевое действие, необходимо указать тип операции Sale, Auth или Verify в параметре action. Дополнительно вы можете использовать и другие параметры, представленные в разделе Параметры вызова.

Пример объекта PaymentOptions, который содержит необязательные параметры (описание платежа и страну пользователя):
```
PaymentOptions *paymentOptions = [[PaymentOptions alloc] initWithProjectID:10
                            paymentID:@"internal_payment_id_1"
                        paymentAmount:1999
                      paymentCurrency:@"USD"
                   paymentDescription:@"T-shirt with dog print"
                           customerID:@"10"
                           regionCode:@"US"];
```
Получите строку для подписывания указанных параметров.
```
paymentOptions.paramsForSignature();
```
Передайте сгенерированную строку в серверную часть приложения.
Сгенерируйте подпись на стороне серверной части приложения и передать ее в клиентскую часть.
Добавьте подпись в объект PaymentOptions.
```
[paymentOptions setSignature:signature]
```
Вызовите платежную форму.
```
[self.JetPaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"JetPaySDK finished with status %ld", (long)result.status);
     ...
 }];
```
После вызова платежной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платежная форма, в других случаях платежная форма не открывается, а метод вызова платежной формы возвращает код ошибки.

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

По умолчанию в SDK для iOS: UI & Core настроено проведение разовой одностадийной оплаты (с типом действия Sale). Для оплаты такого типа можно использовать приведенные выше примеры и дополнительно ничего не настраивать.

SDK для iOS: UI & Core также позволяет проводить и двухстадийные оплаты с блокировкой средств через SDK и последующим списанием. Для этого следует:

Вызовите платежную форму, задав тип действия Auth в объекте paymentOptions:
Рис.: Swift
```
paymentOptions.action = .Auth
```
Рис.: Objective-C
```
[paymentOptions setAction: ActionTypeAuth];
```
Когда потребуется, подтвердите списание средств через Dashboard или через Gate. Чтобы подтвердить списание в Gate, отправьте запрос в конечную точку /v2/payment/card/capture.

Проверка действительности платежных карт

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

Для такой проверки следует вызвать платежную форму, задав тип действия Verify в объекте paymentOptions:

Рис.: Swift

paymentOptions.action = .Verify

Рис.: Objective-C

[paymentOptions setAction: ActionTypeVerify];

Получение информации о платеже

Для получения информации о результатах проведения платежей используются запросы со следующими данными:

Рис.: Прием результатов в Swift

JetPaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("JetPaySDK finished with status \(result.status.rawValue)")
   if let error = result.error {      // в случае ошибки
      print("Error code:\(error.code) with message: \(error.message)")
   }
 }

Рис.: Прием результатов в Objective-C

[self.JetPaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"JetPay SDK finished with status %ld", (long)result.status);
        if(result.error != NULL) {    // в случае ошибки
            NSLog(@"Error code: %@ with message: %@", error.codeString, error.message);
        }
 }];

Допустимые коды результатов проведения платежей, передаваемые в параметре PaymentResult.status:

Код результата	Значение	Описание
`0`	Success	Платеж проведен
`100`	Decline	Платеж отклонен
`200`	Cancelled	Платеж отменен пользователем
`500`	Error	Возникла ошибка при проведении платежа

Проведение платежей с использованием Apple Pay

Чтобы обеспечить возможность проведения платежей с использованием метода Apple Pay, предварительно необходимо:

Зарегистрировать в Apple идентификатор мерчанта (Merchant ID), позволяющий принимать платежи с использованием метода Apple Pay. Этот идентификатор действует бессрочно и может использоваться для разных сайтов и приложений iOS. Информация о регистрации этого идентификатора представлена в документации Apple: Create a merchant identifier.
Выпустить сертификат обработки платежей (Payment Processing Certificate). Этот сертификат используется в связке с идентификатором мерчанта и позволяет обеспечивать безопасность платежных данных при проведении платежей с использованием метода Apple Pay. Информация о выпуске этого сертификата представлена в документации Apple: Create a payment processing certificate.
Передать специалистам технической поддержки JetPay сертификат обработки платежей, используя при этом оговоренные методы защиты.
Включить поддержку Apple Pay для проекта мобильного приложения в используемой среде разработки. Информация об этой настройке для среды Xcode представлена в документации Apple: Enable Apple Pay.

После этого можно проводить платежи с использованием Apple Pay. Все основные процедуры — вызов платежной формы и прием результатов — выполняются при этом так же, как и при работе с другими методами, а при формировании запросов необходимо передавать следующие данные в объекте applePayOptions:

Рис.: Swift

setupApplePayparams(paymentOptions: PaymentOptions) {
        let applePayOptions = PaymentOptions.ApplePayOptions(applePayMerchantID: "merchant.example.com",
                                                             applePayDescription: "Shop",
                                                             countryCode: "US")
        paymentOptions.applePayOptions = applePayOptions
}

Рис.: Objective-C

setApplePaySettings:(PaymentOptions *)paymentOptions {
 PaymentOptionsForApplePay *applePayOptions = [[PaymentOptionsForApplePay alloc]
                                                initWithApplePayMerchantID:@"merchant.example.com"
                                                applePayDescription:@"Shop"
                                                countryCode:@"US"];
}

Все параметры, передаваемые в объекте applePayOptions, обязательны и необходимы для корректного формирования платежного сеанса Apple Pay.

Дополнительные возможности

Дополнение информации о платеже

В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платежной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Информация о процедуре дополнения информации о платеже представлена в отдельной статье.

Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платежной системы и может варьироваться. Список данных, актуальных для конкретного платежа, отображается пользователю в платежном интерфейсе. Пользователь указывает запрашиваемые данные, подтверждает проведение платежа и получает информацию о результате.

Каскадное проведение платежей

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

Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK для iOS: UI & Core поступает уведомление, в котором содержится признак cascading_with_redirect = true. Пользователю при этом отображается страница с ошибкой и кнопкой для выполнения очередной попытки. Если в рамках дополнительной попытки не требуется аутентификация 3‑D Secure, то попытка выполняется без взаимодействия с пользователем, иначе — отображается страница с повторной аутентификацией.

Сбор данных о пользователях

В некоторых случаях вместе с обязательными данными актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Подробная информация об использовании возможности сбора дополнительных данных представлена в отдельной статье.

Управление языком платежного интерфейса

По умолчанию при работе с SDK UI & Core в платежном интерфейсе используется язык устройства пользователя, если он поддерживается для используемого проекта, или язык, определенный по умолчанию для остальных случаев (в общем случае — английский). Вместе с тем, если это актуально, можно задавать определенные языки для конкретных сеансов. Для этого в каждом таком случае при вызове платежной формы необходимо передавать соответствующий код языка в параметре languageCode (подробнее).

Внимание: При указании языка, не поддерживаемого для используемого проекта, платежная форма не открывается и пользователю отображается информация об ошибке.

Платформа позволяет подключать и использовать в интерфейсе SDK разные языки. Вот перечень кодов доступных для подключения языков:

de — немецкий;
en — английский;
es — испанский;
fr — французский;
hu — венгерский;
it — итальянский;
kk — казахский;
ru — русский.

Сохранение платежных данных

При работе с SDK для iOS: UI & Core поддерживается сохранение платежных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Возможность сохранения платежных данных подключается для каждого проекта отдельно; со стороны мерчанта необходимо сообщить специалистам технической поддержки подходящий вариант сохранения: всегда или по выбору пользователя. Информация об этой возможности представлена в отдельной статье (подробнее).

В результате сохранения платежных данных для каждого платежного инструмента формируется идентификатор, ассоциированный с идентификатором конкретного пользователя (customerId). Для отображения пользователю сохраненных данных его платежных инструментов в объекте PaymentOptions необходимо передавать параметр hideSavedWallets со значением false.

Параметры вызова

Для работы с SDK для iOS: UI & Core в объекте PaymentOptions можно использовать следующие дополнительные параметры.

Параметр	Описание
`paymentDescription` string	Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase`
`receiptData` string	Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`
`hideSavedWallets` boolean	Параметр, позволяющий управлять отображением сохраненных ранее платежных инструментов. Возможные значения: `true` — не отображать сохраненные данные. `false` — отображать сохраненные данные.
`forcePaymentMethod` string	Код предварительно выбранного платежного метода. Эти коды перечислены в разделе Коды поддерживаемых платежных методов на Payment Page. Пример: `card`
`threeDSecureInfo` object	Объект, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2
`languageCode` string	Код языка отображения платежного интерфейса в формате ISO 639-1 alpha-2. Должен соответствовать одному из языков, поддерживаемых для используемого проекта. Пример: `IT`
`regionCode` string	Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `SE`
`applePayMerchantID` string	Идентификатор мерчанта в сервисе Apple Pay.
`applePayDescription` string	Сведения о мерчанте в сервисе Apple Pay.
`countryCode` string	Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Передается при проведении платежей с использованием Apple Pay. Пример: `SE`
`logoImage` object	Файл с логотипом мерчанта в формате PNG или SVG.
`brandColor` object	Цвет платежного интерфейса, передается в виде объекта `UIColor`. Пример: `UIColor.green`
`additionalFields` list	Дополнительные поля с информацией о пользователе. Содержит список параметров и может включать их значения. Пример: `AdditionalField(type: .customer_first_name, value: "Sonya")`

Параметры для работы с повторяемыми оплатами необходимо передавать в объекте recurrentInfo, который входит в объект PaymentOptions.

Табл. 1.
Параметр	Описание
`type` string	Указатель типа повторяемой оплаты : `.OneClick` — экспресс-оплата `.Autopayment` — автооплата `.Regular` — регулярная оплата
`period` string	Периодичность списаний регулярной оплаты. Возможные значения: `.Day` — ежедневно `.Week` — еженедельно `.Month` — ежемесячно `.Quarter` — ежеквартально `.Year` — ежегодно
`expiryDay` string	День окончания действия повторяемой оплаты
`expiryMonth` string	Месяц окончания действия повторяемой оплаты
`expiryYear` integer	Год окончания действия повторяемой оплаты
`scheduledPaymentID` string	Идентификатор, который необходимо присвоить повторяемой оплате (для автоматического инициирования списаний). Параметр следует передавать вместе с параметром `startDate`
`startDate` string	Дата первого списания в формате `dd-mm-yyyy` (параметр обязательно используется в связке с параметром `scheduledPaymentID`)
`time` string	Время выполнения последующих списаний (для регулярной оплаты) в формате `hh:mm:ss`, передается, если указан параметр `period`
`schedule` object — расписание проведения повторяемых оплат (можно задать со стороны мерчанта). Следует указать параметры `amount` и `date`
`amount` integer	Фиксированная сумма последующих списаний в дробных единицах валюты
`date` string	Дата списания в формате `dd-mm-yyyy`

В объекте threeDSecureInfo можно использовать следующие дополнительные объекты и параметры.

Параметр	Описание
`threeDSecureInfo` — объект класса `ThreeDSecureInfo`, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2
`threeDSecurePaymentInfo` — объект класса `ThreeDSecurePaymentInfo`, содержащий информацию о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации
`challengeIndicator` string	Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения: `01` — без предпочтений, `02` — предпочтительно не выполнять, `03` — предпочтительно выполнять, `04` — обязательно выполнять
`challengeWindow` string	Размер окна для открытия страницы аутентификации. Возможные значения: `01` — 250 x 400 пикселей, `02` — 390 x 400 пикселей, `03` — 500 x 600 пикселей, `04` — 600 x 400 пикселей, `05` — полноэкранный режим
`preorderDate` string	Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`
`preorderPurchase` string	Индикатор предварительного заказа. Возможные значения: `01` — не является предварительным заказом, `02` — является предварительным заказом
`reorder` string	Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения: `01` — первичная покупка, `02` — повторная покупка
`threeDSecureGiftCardInfo` — объект класса `ThreeDSecureGiftCardInfo`, содержащий информацию об оплате предоплаченными или подарочными картами
`amount` integer	Общая сумма оплаты предоплаченными или подарочными картами в дробных единицах валюты
`currency` string	Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 (например, GBP)
`count` integer	Количество предоплаченных или подарочных карт, использованных для оплаты
`threeDSecureCustomerInfo` — объект класса `ThreeDSecureCustomerInfo`, содержащий информацию о пользователе
`addressMatch` string	Указатель совпадения платежного адреса пользователя с адресом доставки, указанным в объекте `threeDSecureShippingInfo`. Возможные значения: Y — адреса совпадают, N — адреса не совпадают
`billingRegionCode` string	Код штата, провинции или региона страны в формате ISO 3166-2, например `MOS` для Московской области.
`homePhone` string	Номер домашнего телефона пользователя, может содержать только цифры, от четырех до двадцати четырех (например, `44991234567`)
`workPhone` string	Номер рабочего телефона пользователя, может содержать только цифры, от четырех до двадцати четырех (например, `44997654321`)
`threeDSecureAccountInfo` — объект класса `ThreeDSecureAccountInfo`, содержащий информацию об учетной записи пользователя на стороне мерчанта
`additional` string	Дополнительная информация об учетной записи пользователя, например ее идентификатор; в произвольном формате с использованием до шестидесяти четырех символов
`activityDay` integer	Количество попыток проведения оплаты за последние 24 часа, не более трех символов (`999`)
`activityYear` integer	Количество попыток проведения оплаты за последние 365 дней, не более трех символов (`999`)
`ageIndicator` string	Количество дней с момента создания учетной записи пользователя. Возможные значения: `01` — платеж проводится без аутентификации в учетной записи, `02` — учетная запись создана в день проведения платежа, `03` — менее 30 дней, `04` — от 30 до 60 дней, `05` — более 60 дней
`authData` string	Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов
`authMethod` string	Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения: `01` — доступ без аутентификации; `02` — аутентификация с использованием данных, сохраненных на стороне мерчанта; `03` — аутентификация с использованием Federated ID (например, Google Account или Facebook); `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online (FIDO)
`authTime` string	Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`
`date` string	Дата создания учетной записи в формате `ДД-ММ-ГГГГ`
`changeDate` string	Дата последних изменений в учетной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`
`changeIndicator` string	Количество дней с момента последних изменений в учетной записи, за исключением изменения или сброса пароля. Возможные значения: `01` — изменения в день проведения платежа, `02` — менее 30 дней, `03` — от 30 до 60 дней, `04` — более 60 дней
`passChangeDate` string	Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`
`passChangeIndicator` string	Количество дней с момента последнего изменения или сброса пароля. Возможные значения: `01` — пароль не был изменен или сброшен, `02` — пароль был изменен или сброшен в день проведения платежа, `03` — менее 30 дней, `04` — от 30 до 60 дней, `05` — более 60 дней
`paymentAge` string	Дата добавления платежных данных карты в формате `ДД-ММ-ГГГГ`
`paymentAgeIndicator` string	Количество дней с момента сохранения данных платежной карты, используемой для проведения платежа, в учетной записи пользователя. Возможные значения: `01` — платеж проводится без аутентификации в учетной записи, `02` — данные карты сохранены в день проведения платежа, `03` — менее 30 дней, `04` — от 30 до 60 дней, `05` — более 60 дней
`provisionAttempts` integer	Количество попыток сохранения новых платежных данных карты за последние 24 часа, не более трех символов (`999`)
`purchaseNumber` integer	Количество покупок, совершенных через эту учетную запись за последние 6 месяцев, не более четырех символов (`9999`)
`suspiciousActivity` string	Индикатор подозрительной активности. Возможные значения: `01` — без подозрений, `02` — с подозрительной активностью
`threeDSecureShippingInfo` — объект класса `ThreeDSecureShippingInfo`, содержащий информацию о доставке
`address` string	Адрес доставки, не более 150 символов
`addressUsage` string	Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате `ДД-ММ-ГГГГ`
`addressUsageIndicator` string	Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения: `01` — указанный адрес используется впервые, `02` — менее 30 дней назад, `03` — от 30 до 60 дней назад, `04` — более 60 дней назад
`city` string	Название города доставки, не более 50 символов
`country` string	Код страны доставки в формате ISO 3166-1 alpha-2, например `GB` для Великобритания
`deliveryEmail` string	Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов
`deliveryTime` string	Срок доставки. Возможные значения: `01` — электронная доставка в день покупки, `02` — доставка в день покупки, `03` — доставка на следующий день после покупки, `04` — доставка более чем через один день после покупки
`nameIndicator` string	Индикатор совпадения имени пользователя с именем получателя. Возможные значения: `01` — имена совпадают, `02` — имена не совпадают
`postal` string	Почтовый индекс доставки, не более 16 символов
`regionCode` string	Код штата, провинции или региона страны в формате ISO 3166-2, например `SPE` для Санкт-Петербурга. При указании значения этого параметра также необходимо указать значение параметра `country` в объекте `threeDSecureShippingInfo`
`type` string	Способ доставки, выбранный пользователем. Возможные значения: `01` — доставка на платежный адрес держателя карты; `02` — доставка на другой подтвержденный адрес; `03` — доставка на адрес, не совпадающий с платежным и не являющийся подтвержденным; `04` — доставка в магазин; `05` — электронная доставка; `06` — без доставки (например, в случае покупки билетов на мероприятие); `07` — другое
`threeDSecureMpiResultInfo` — объект класса `ThreeDSecureMpiResultInfo`, содержащий информацию о предыдущей аутентификации пользователя.
`acsOperationId` string	Идентификатор предыдущей операции пользователя на стороне эмитента, не более 36 символов.
`authenticationFlow` string	Указатель варианта предыдущего прохождения аутентификации пользователем. Возможные значения: `01` — frictionless flow, `02` — challenge flow
`authenticationTimestamp` string	Дата и время предыдущей успешной аутентификации пользователя.