SDK UI & Core для Android

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

Введение

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

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

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

Возможности

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

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

Схема работы

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

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

Интерфейс

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

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

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

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

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

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

Установка библиотек

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

  1. Открыть в приложении модуль build.gradle.kts.
  2. Указать в секции repositories репозиторий mavenCentral:
    allprojects {
        repositories {
            google()
            mavenCentral()
        }
    }
  3. Добавить в секцию dependencies следующее:
    implementation "com.ecommpay:msdk-ui:LATEST_VERSION"

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

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

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

Перед проведением реальных платежей через SDK UI & Core для Android рекомендуется протестировать проведение платежей с использованием тестового проекта. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде ecommpay (сделать это можно через сайт компании). Также по согласованию со специалистами ecommpay можно протестировать использование метода Google Pay и дополнительных возможностей, таких как каскадное проведение платежей и сбор данных о пользователях.

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

  1. Открыть в приложении модуль build.gradle.kts.
  2. Указать идентификатор тестового проекта (projectId) и секретный ключ от него (projectSecretKey).
  3. Запустить процесс синхронизации gradle.

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

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

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

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

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

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

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

  1. Создать объект EcmpPaymentInfo.
    • Этот объект должен содержать следующие обязательные параметры:
      • projectId (integer) — идентификатор проекта, полученный от ecommpay;
      • paymentId (string) — идентификатор платежа, уникальный в рамках проекта;
      • paymentCurrency (string) — код валюты платежа в формате ISO-4217 alpha-3;
      • paymentAmount (integer) — сумма платежа в дробных единицах валюты;
      • customerId (string) — идентификатор пользователя в рамках проекта;
      • signature (string) — подпись запроса, составленная после указания всех целевых параметров.
    • Дополнительно могут использоваться и другие параметры, представленные в следующей таблице.
    val ecmpPaymentInfo = EcmpPaymentInfo(
          projectId = 77655,
          paymentId = payment_322,
          paymentAmount = 100,
          paymentCurrency = "USD",
          paymentDescription = "Cosmoshop payment",    //Описание платежа
          customerId = "customer_003",
          regionCode = "DE",      //Код страны проживания пользователя
          token = "o8i7u65y4t3rkjhgfdw3456789oikjhgfdfghjkl...", //Токен платёжных данных
          languageCode = "de",    //Код языка отображения платёжного интерфейса
          receiptData = "eyAKICAicG9zaXRpb25zIjpbIAxLAogICAgICAgICJhbW91bnQiOjU5OTAsCiAgQ==",
          //Данные уведомления с информацией о товарных позициях
          hideSavedWallets = false, // Параметр отображения сохранённых платёжных данных
          forcePaymentMethod = card //Код предварительно выбранного платёжного метода
       )
  2. Подписать параметры из объекта EcmpPaymentInfo.
    ecmpPaymentInfo.signature = SignatureGenerator.generateSignature(
           paramsToSign = ecmpPaymentInfo.getParamsForSignature(),
           secret = SECRET_KEY
       )
  3. Создать объект EcmpPaymentOptions, который должен содержать обязательный параметр actionType (string). В этом параметре необходимо указать целевое действие: тип операции Sale, Auth или Verify. Дополнительно для аутентификации 3‑D Secure может потребоваться указать адрес электронной почты пользователя (CUSTOMER_EMAIL) или номер его телефона (CUSTOMER_PHONE), а также рекомендуется указать следующие сведения о платёжном адресе пользователя:
    • BILLING_COUNTRY — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 (подробнее);
    • BILLING_POSTAL — индекс платёжного адреса пользователя;
    • BILLING_CITY — название города платёжного адреса пользователя;
    • BILLING_ADDRESS — название улицы платёжного адреса пользователя.

    Также могут быть указаны другие объекты и параметры, представленные в следующей таблице.

    Следующий пример помимо обязательных объекта EcmpPaymentInfo и параметра actionType содержит ряд дополнительных параметров, в том числе объект additionalFields с данными, которые отображаются в полях для сбора информации о пользователе, включая данные, которые могут потребоваться для аутентификации 3‑D Secure.

    val paymentOptions = paymentOptions {
            paymentInfo = ecmpPaymentInfo
            actionType = EcmpActionType.Sale
            brandColor = "#800008"
            isDarkTheme = false
            logoImage = BitmapFactory.decodeResource(resources, R.drawable.example_logo)
            hideScanningCards = false 
            isTestEnvironment = true
            merchantId = BuildConfig.GPAY_MERCHANT_ID
            merchantName = "Example Merchant Name"
            screenDisplayModes {
              mode(EcmpScreenDisplayMode.HIDE_DECLINE_FINAL_SCREEN)
              mode(EcmpScreenDisplayMode.HIDE_SUCCESS_FINAL_SCREEN)
            }
            additionalFields {
              field {
                type = EcmpAdditionalFieldType.CUSTOMER_EMAIL
                value = "mail@mail.com"
              }
              field {
                type = EcmpAdditionalFieldType.CUSTOMER_PHONE
                value = "customerPhone"
              }
              field {
                type = EcmpAdditionalFieldType.CUSTOMER_FIRST_NAME
                value = "firstName"
              }
            }
    }
  4. Создать объект EcmpPaymentSDK.
    val sdk = EcmpPaymentSDK(
            context = applicationContext,
            paymentOptions = paymentOptions,
           )

    При необходимости платёжную форму можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок протестировать проведение оплат с определённым результатом. Для этого в запросе на открытие платёжной формы в объекте EcmpPaymentSDK следует передать значение EcmpPaymentSDK.EcmpMockModeType.SUCCESS для параметра mockModeType (если необходим результат — платёж проведён). Также можно использовать значения EcmpPaymentSDK.EcmpMockModeType.DECLINE (если необходим результат — платёж отклонён) и EcmpPaymentSDK.EcmpMockModeType.DISABLED (для открытия формы в рабочем режиме).

  5. Открыть платёжный интерфейс.
    sdk.openPaymentScreen(this, 1234)

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

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

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

  1. Вызвать платёжную форму, задав тип действия EcmpActionType.Auth в объекте paymentOptions:
    (EcmpPaymentOptions.EcmpActionType.Auth);
  2. Когда потребуется, подтвердить списание средств через Dashboard (подробнее) или через Gate (с помощью запроса к конечной точке /v2/payment/card/capture).

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

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

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

(EcmpPaymentOptions.EcmpActionType.Verify);

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

Для получения уведомлений о результатах проведения платежей используется метод onActivityResult.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
 
        when (resultCode) {
            EcmpPaymentSDK.RESULT_SUCCESS -> {
                Toast.makeText(this, "Payment was finished successfully", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was finished successfully")
            }
            EcmpPaymentSDK.RESULT_CANCELLED -> {
                Toast.makeText(this, "Payment was cancelled", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was cancelled")
            }
            EcmpPaymentSDK.RESULT_DECLINE -> {
                Toast.makeText(this, "Payment was declined", Toast.LENGTH_SHORT).show()
                Log.d("PaymentSDK", "Payment was declined")
            }
            EcmpPaymentSDK.RESULT_ERROR -> {
                val errorCode = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_CODE)
                val message = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_MESSAGE)
                Toast.makeText(this, "Payment was interrupted. See logs", Toast.LENGTH_SHORT).show()
                Log.d(
                    "PaymentSDK",
                    "Payment was interrupted. Error code: $errorCode. Message: $message"
                )
            }
        }
    }

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

  • RESULT_SUCCESS — платёж проведён;
  • RESULT_CANCELLED — платёж отменён;
  • RESULT_DECLINE — платёж отклонён;
  • RESULT_ERROR — возникла ошибка при проведении платежа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

paymentDescription
string

Описание платежа. Представляет собой строку длиной не более 255 символов.

Пример: Cosmoshop purchase

receiptData
string

Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64.

Пример: eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg

token
string

Токен платёжных данных. Представляет собой строку длиной не более 255 символов.

Пример: 6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c

hideSavedWallets
boolean

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

Возможные значения:

  • true — не отображать сохранённые данные.
  • false — отображать сохранённые данные.

forcePaymentMethod
string

Код предварительно выбранного платёжного метода в соответствии с таблицей.

Пример: card

ecmpThreeDSecureInfo
object

Объект, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2

languageCode
string

Код языка отображения платёжного интерфейса в формате ISO 639-1 alpha-2. Должен соответствовать одному из языков, поддерживаемых для используемого проекта.

Пример: IT

regionCode

string

Код страны проживания пользователя в формате ISO 3166-1 alpha-2.

Пример: RU

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

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

merchantID
string

Идентификатор мерчанта в сервисе Google Pay.

merchantName
string

Наименование мерчанта в сервисе Google Pay.

logoImage
bitmap

Файл с логотипом мерчанта в формате BMP.

brandColor
string

Цвет платёжного интерфейса в шестнадцатеричном формате HEX.

Пример: #800080

isTestEnvironment
boolean

Признак тестового платежа.

Возможные значения:

  • true — тестовый платёж.
  • false — платёж в рабочем режиме.

additionalFields
list

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

Пример: EcmpAdditionalField(EcmpAdditionalFieldType.CUSTOMER_EMAIL,"mail@mail.com")

recipientInfo
object — объект, содержащий сведения о получателе платежа

pan
string

Номер карты.

Пример: 5443011850290191

card_holder
string

Имя и фамилия (в соответствии с указанными на карте).

Пример: Sonya Kovalevsky

wallet_id
string

Номер электронного кошелька.

Пример: WID301185029011891

wallet_owner
string

Имя и фамилия получателя.

Пример: Sonya Kovalevsky

country
string

Код страны проживания в формате ISO 3166-1 alpha-2.

Пример: SE

address
string

Адрес проживания.

Пример: Albanovaegen 28

city
string

Город проживания.

Пример: Stockholm

state
string

Штат проживания.

Пример: MN

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

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

type
string

Указатель типа повторяемой оплаты :

  • C — экспресс-оплата (OneClick)
  • U — автооплата
  • R — регулярная оплата

period
string

Периодичность списаний регулярной оплаты.

Возможные значения:

  • D — ежедневно
  • W — еженедельно
  • M — ежемесячно
  • Q — ежеквартально
  • Y — ежегодно

expiry_day
string

День окончания действия повторяемой оплаты

expiry_month
string

Месяц окончания действия повторяемой оплаты

expiry_year
integer

Год окончания действия повторяемой оплаты

scheduled_payment_id
string

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

Параметр следует передавать вместе с параметром start_date

start_date
string

Дата первого списания в формате dd-mm-yyyy (параметр обязательно используется в связке с параметром scheduled_payment_id)

time
string

Время выполнения последующих списаний (для регулярной оплаты) в формате hh:mm:ss; передаётся, если указан параметр period

schedule
object — расписание проведения повторяемых оплат (можно задать со стороны мерчанта). Следует указать параметры amount и date

amount
integer

Фиксированная сумма последующих списаний в дробных единицах валюты

date
string

Дата списания в формате dd-mm-yyyy

В объекте ecmpThreeDSecureInfo можно использовать следующие дополнительные объекты и параметры. Их использование позволит повысить вероятность выбора варианта аутентификации 3‑D Secure без дополнительных действий со стороны пользователя (frictionless flow).

Параметр Описание
threeDSecureInfo — объект класса ECMPThreeDSecureInfo, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2
threeDSecurePaymentInfo — объект класса ECMPThreeDSecurePaymentInfo, содержащий информацию о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации

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 — объект класса ECMPThreeDSecureGiftCardInfo, содержащий информацию об оплате предоплаченными или подарочными картами

amount
integer

Общая сумма оплаты предоплаченными или подарочными картами в дробных единицах валюты

currency
string

Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 (например, GBP)

count
integer

Количество предоплаченных или подарочных карт, использованных для оплаты
threeDSecureCustomerInfo — объект класса ECMPThreeDSecureCustomerInfo, содержащий информацию о пользователе

addressMatch
string

Указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте threeDSecureShippingInfo.

Возможные значения:
  • Y — адреса совпадают,
  • N — адреса не совпадают

billingRegionCode
string

Код штата, провинции или региона страны в формате ISO 3166-2, например MOS для Московской области.

homePhone
string

Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44991234567)

workPhone
string

Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44997654321)
threeDSecureAccountInfo — объект класса ECMPThreeDSecureAccountInfo, содержащий информацию об учётной записи пользователя на стороне мерчанта;

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 — объект класса ECMPThreeDSecureShippingInfo, содержащий информацию о доставке

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

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