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 с примерами кода на языках Swift и Objective-C.

Возможности

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

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

Схема работы

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

  1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом.
  2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK UI & Core для iOS этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта.
  3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK UI & Core для iOS.
  4. С помощью SDK UI & Core для iOS инициируется создание платёжной сессии в платёжной платформе.
  5. На стороне платёжной платформы выполняются подготовка платёжного интерфейса с учётом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса.
  6. В мобильном приложении пользователю отображается форма оплаты.
  7. Пользователь выбирает платёжный метод (если он не был задан при открытии платёжной сессии), указывает необходимую информацию и подтверждает готовность провести оплату.
  8. От SDK UI & Core для iOS к платёжной платформе отправляется запрос на проведение оплаты.
  9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам.
  10. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате.
  11. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты.
  12. От платёжной платформы к SDK UI & Core для iOS направляется информация о результате оплаты.
  13. Информация о результате отображается в пользовательском интерфейсе.

Интерфейс

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

Рис. 1. Варианты индивидуального оформления
Рис. 2. Страница указания платёжных данных
Рис. 3. Страница уведомления о результате платежа

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

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

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

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

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

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

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

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

  4. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

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

    Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.

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

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

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

  1. Перенести файл ecommpaySDK.xcframework в папку проекта мобильного приложения.
  2. Добавить библиотеку к проекту. В 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.
  3. Добавить ключ NSCameraUsageDescription со значением permission is needed in order to scan card в файл Info.plist, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование.

  4. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

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

    Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.

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

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

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

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

  3. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ NSLocationWhenInUseUsageDescription со значением fraud prevention в файл Info.plist.

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

    Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить.

  4. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ 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, заданы постоянные значения для этих параметров.

Рис. 4. Swift
 let secret = "your_secret" // секретный ключ для тестового проекта
    let project_id: Int32 = 10 // идентификатор тестового проекта
Рис. 5. Objective-C
#define SECRET @"your_secret" // секретный ключ для тестового проекта
#define PROJECT_ID 10 // идентификатор тестового проекта

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

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

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

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

Вызов в Swift

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

  1. Импортировать библиотеку.
    import ecommpaySDK
  2. Объявить библиотеку EcommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
    let ecommpaySDK = EcommpaySDK()
  3. Создать объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectId (integer) — идентификатор проекта, полученный от ecommpay;
    • paymentId (string) — идентификатор платежа, уникальный в рамках проекта;
    • paymentCurrency (string) — код валюты платежа в формате ISO-4217 alpha-3;
    • paymentAmount (integer) — сумма платежа в дробных единицах валюты;
    • customerId (string) — идентификатор пользователя в рамках проекта;

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

    Чтобы задать целевое действие, необходимо указать тип операции 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")
  4. Получить строку для подписывания указанных параметров.
    paymentOptions.paramsForSignature();
  5. Передать сгенерированную строку в серверную часть приложения.
  6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  7. Добавить подпись в объект PaymentOptions.
    paymentOptions.signature = signature;
  8. Вызвать платёжную форму.
    ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in
         print("ecommpaySDK finished with status \(result.status.rawValue)")
   ...
 }

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

Вызов в Objective-C

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

  1. Импортировать библиотеку.
    #import <EcommpaySDK/EcommpaySDK.h>
  2. Объявить библиотеку EcommpaySDK в любом месте приложения (например, внутри метода viewDidLoad).
    EcommpaySDK *self.EcommpaySDK = [[EcommpaySDK alloc] init];
  3. Создать объект PaymentOptions. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectId (integer) — идентификатор проекта, полученный от ecommpay;
    • paymentId (string) — идентификатор платежа, уникальный в рамках проекта;
    • paymentCurrency (string) — код валюты платежа в формате ISO-4217 alpha-3;
    • paymentAmount (integer) — сумма платежа в дробных единицах валюты;
    • customerId (string) — идентификатор пользователя в рамках проекта;

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

    Чтобы задать целевое действие, необходимо указать тип операции 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"];
  4. Получить строку для подписывания указанных параметров.
    paymentOptions.paramsForSignature();
  5. Передать сгенерированную строку в серверную часть приложения.
  6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  7. Добавить подпись в объект PaymentOptions.
    [paymentOptions setSignature:signature]
  8. Вызвать платёжную форму.
    [self.EcommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"EcommpaySDK finished with status %ld", (long)result.status);
     ...
 }];

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

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

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

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

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

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

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

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

Рис. 8. Swift
paymentOptions.action = .Verify
Рис. 9. Objective-C
[paymentOptions setAction: ActionTypeVerify];

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

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

Рис. 10. Приём результатов в 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)")
   }
 }
Рис. 11. Приём результатов в Objective-C
[self.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions 
     completionHandler:^(PaymentResult *result) {
     NSLog(@"EcommpaySDK 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, предварительно необходимо:

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

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

Рис. 12. Swift
setupApplePayparams(paymentOptions: PaymentOptions) {
        let applePayOptions = PaymentOptions.ApplePayOptions(applePayMerchantID: "merchant.example.com",
                                                             applePayDescription: "Shop",
                                                             countryCode: "US")
        paymentOptions.applePayOptions = applePayOptions
}
Рис. 13. 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.

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

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

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

customer_email
list

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

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

customer_phone
list

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

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

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

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

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

 Дата и время предыдущей успешной аутентификации пользователя.