SDK UI & Core для iOS

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

Введение

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

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

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

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

Возможности

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

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

При проведении платежей с использованием карт и метода Apple Pay задействуется платёжный интерфейс, описанный в этой статье, а при проведении платежей с использованием других платёжных методов — платёжная форма Payment Page.

Схема работы

В общем случае оплаты с использованием 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. Со стороны мерчанта можно настраивать цвет этого интерфейса и добавлять логотип.

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

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

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

Рис.: 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. Остальные параметры можно передать в этом же объекте, а также запросить их у пользователя или получить со стороны платёжной платформы.

Вызов в 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) — идентификатор пользователя в рамках проекта;

    Дополнительно могут использоваться и другие параметры, представленные в разделе Параметры вызова.

    Пример объекта 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) — идентификатор пользователя в рамках проекта;

    Дополнительно могут использоваться и другие параметры, представленные в разделе Параметры вызова.

    Пример объекта 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(@"ECommPay SDK finished with status %ld", (long)result.status);
         ...
     }];

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

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

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

Рис.: Приём результатов в 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, предварительно необходимо:

  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:

Рис.: 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

Для работы с 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

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

Адрес доставки, не более ста пятидесяти символов

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

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