SDK UI & Core для iOS

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

Введение

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

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

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

Список версий SDK UI & Core для iOS: https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases
Примеры кода: https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples

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

Возможности

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

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

Схема работы

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

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

Интерфейс

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

Рис.: Варианты индивидуального оформления

Рис.: Страница указания платёжных данных

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

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

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

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

При возникновении вопросов о работе с SDK UI & Core для iOS следует обращаться в службу технической поддержки ecommpay (support@ecommpay.com).

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

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

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

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

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

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

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

Перенести файл ecommpaySDK.xcframework в папку проекта мобильного приложения.
Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо:
1. Открыть цель (target) проекта.
2. Перейти в General > Embedded Binaries.
3. Щёлкнуть +.
4. Щёлкнуть Add Other.
5. Выбрать файл ecommpaySDK.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.

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

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

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

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

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

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

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

Обеспечение работы с подписью

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

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

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

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

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

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

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

Рис.: Swift

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

Рис.: Objective-C

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

Чтобы перейти в рабочий режим, необходимо заменить тестовые значения (идентификатор рабочего проекта и секретный ключ от него) на рабочие.

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

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

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

Внимание: С 12 августа 2024 года в связи с вступлением в силу новых требований платёжной системы Visa расширяется набор параметров, необходимых для аутентификации 3‑D Secure при проведении оплат с использованием карт этой платёжной системы. Параметры, которые становятся обязательными для таких случаев, перечислены далее.

Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя, подробнее далее) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения.

Вызов в Swift

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

Импортировать библиотеку.
```
import ecommpaySDK
```
Объявить библиотеку EcommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
```
let ecommpaySDK = EcommpaySDK()
```
Создать объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
- projectId (integer) — идентификатор проекта, полученный от ecommpay;
- 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;
```
Вызвать платёжную форму.
```
ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("ecommpaySDK finished with status \(result.status.rawValue)")
   ...
 }
```
После вызова платёжной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платёжная форма, в других случаях платёжная форма не открывается, а метод вызова платёжной формы возвращает код ошибки.

Вызов в Objective-C

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

Импортировать библиотеку.
```
#import <EcommpaySDK/EcommpaySDK.h>
```
Объявить библиотеку EcommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
```
EcommpaySDK *self.ecommpaySDK = [[EcommpaySDK alloc] init];
```
Создать объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
- projectId (integer) — идентификатор проекта, полученный от ecommpay;
- 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.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"ECommPay SDK finished with status %ld", (long)result.status);
     ...
 }];
```
После вызова платёжной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платёжная форма, в других случаях платёжная форма не открывается, а метод вызова платёжной формы возвращает код ошибки.

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

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

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

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

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

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

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

Рис.: Swift

paymentOptions.action = .Verify

Рис.: Objective-C

[paymentOptions setAction: ActionTypeVerify];

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

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

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

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

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

[self.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"ECommPay 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.
Передать специалистам технической поддержки ecommpay сертификат обработки платежей, используя при этом оговорённые методы защиты.
Включить поддержку 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.

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

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

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

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

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

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

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

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

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

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

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

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

К числу поддерживаемых в платформе для интерфейса SDK и доступных для оперативного подключения в проектах относятся следующие языки.

Язык	Код
Английский	en
Венгерский	hu
Испанский	es
Итальянский	it
Немецкий	de
Французский	fr

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

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

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

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

Начиная с 12 августа 2024 года при проведении оплат с использованием карт платёжной системы Visa в запросах в объекте PaymentOptions необходимо передавать параметр additionalFields с по крайней мере одним из следующих полей.

Параметр Описание

Параметр	Описание
`customer_email` list	Адрес электронной почты пользователя. Пример: `AdditionalField(type: .customer_email, value: "Customer email")`
`customer_phone` list	Номер телефона пользователя. Пример: `AdditionalField(type: .customer_phone, value: "Customer phone")`

customer_email
list

Адрес электронной почты пользователя.

Пример: AdditionalField(type: .customer_email, value: "Customer email")

customer_phone
list

Номер телефона пользователя.

Пример: AdditionalField(type: .customer_phone, value: "Customer phone")

Дополнительно при проведении оплат с использованием платёжных карт любых платёжных систем в параметре additionalFields рекомендуется передавать следующие сведения о платёжном адресе пользователя.

Параметр	Описание
`billing_country` string	Код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 (подробнее). Пример: `AdditionalField(type: .customer_billing_country, value: "SE")`
`billing_city` string	Город платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_city, value: "Stockholm")`
`billing_postal` string	Индекс платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_postal, value: "10691")`
`billing_address` string	Название улицы платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_address, value: "Albanovaegen 28")`

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

Параметр	Описание
`paymentDescription` string	Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase`
`receiptData` string	Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg`
`hideSavedWallets` boolean	Параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов. Возможные значения: `true` — не отображать сохранённые данные. `false` — отображать сохранённые данные.
`forcePaymentMethod` string	Код предварительно выбранного платёжного метода в соответствии с таблицей. Пример: `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 можно использовать следующие дополнительные объекты и параметры. Их использование позволит повысить вероятность выбора варианта аутентификации 3‑D Secure без дополнительных действий со стороны пользователя (frictionless flow).

Параметр	Описание
`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	Адрес доставки, не более ста пятидесяти символов
`addressUsage` string	Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате `ДД-ММ-ГГГГ`
`addressUsageIndicator` string	Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения: `01` — указанный адрес используется впервые, `02` — менее 30 дней назад, `03` — от 30 до 60 дней назад, `04` — более 60 дней назад
`city` string	Название города доставки, не более пятидесяти символов
`country` string	Код страны доставки в формате ISO 3166-1 alpha-2 (например, GB)
`deliveryEmail` string	Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов
`deliveryTime` string	Срок доставки. Возможные значения: `01` — электронная доставка в день покупки, `02` — доставка в день покупки, `03` — доставка на следующий день после покупки, `04` — доставка более чем через один день после покупки
`nameIndicator` string	Индикатор совпадения имени пользователя с именем получателя. Возможные значения: `01` — имена совпадают, `02` — имена не совпадают
`postal` string	Почтовый индекс доставки, не более шестнадцати символов
`regionCode` string	Код штата, провинции или региона страны в формате ISO 3166-2, например `SPE` для Санкт-Петербурга. При указании значения этого параметра также необходимо указать значение параметра `country` в объекте `threeDSecureShippingInfo`
`type` string	Способ доставки, выбранный пользователем. Возможные значения: `01` — доставка на платёжный адрес держателя карты; `02` — доставка на другой подтверждённый адрес; `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым; `04` — доставка в магазин; `05` — электронная доставка; `06` — без доставки (например, в случае покупки билетов на мероприятие); `07` — другое
`threeDSecureMpiResultInfo` — объект класса `ThreeDSecureMpiResultInfo`, содержащий информацию о предыдущей аутентификации пользователя.
`acsOperationId` string	Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов.
`authenticationFlow` string	Указатель варианта предыдущего прохождения аутентификации пользователем. Возможные значения: `01` — frictionless flow, `02` — challenge flow
`authenticationTimestamp` string	Дата и время предыдущей успешной аутентификации пользователя.