# SDK UI & Core для Android {#ru_sdk_ui_and_core_android}

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



**На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md)

## Общая информация {#ru_sdk_ui_and_core_android_overview}

### Введение {#section_spc_d32_2vb .section}

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: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases)
-   Примеры кода: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example)

### Возможности {#section_rdk_l32_2vb .section}

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

-   Проведение платежей различных типов с прямым использованием платёжных карти с применением метода Google Pay, а также других платёжных методов, доступных в рамках проекта мерчанта. К поддерживаемым типам платежей относятся:

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

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

### Схема работы {#section_lws_232_2vb .section}

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

![](images/sdk/android/ru_sdk_ui_core_functional.svg)

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. Информация о результате отображается в пользовательском интерфейсе.

### Интерфейс {#section_rsg_3jf_fvb .section}

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

![](images/sdk/android/all_sdk_ui_core_design_color.svg "Варианты индивидуального оформления")

![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Страница указания платёжных данных")

![](images/sdk/android/all_sdk_ui_core_design_result.png "Страница уведомления о результате платежа")

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

### Порядок интеграции {#section_slp_nvf_fvb .section}

Для подключения веб-сервиса к платёжной платформе 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.  Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md).
    2.  Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay.

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

### Установка библиотек {#section_fr4_txf_fvb .section}

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

1.  Открыть в приложении модуль `build.gradle.kts`.
2.  Указать в секции `repositories` репозиторий `mavenCentral`:

    ```language-json
    allprojects {
        repositories {
            google()
            mavenCentral()
        }
    }
    ```

3.  Добавить в секцию `dependencies` следующее:

    ```language-json
    implementation "com.ecommpay:msdk-ui:LATEST\_VERSION"
    ```


### Обеспечение работы с подписью {#section_nsw_rbg_fvb .section}

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

## Тестирование {#ru_sdk_ui_and_core_android_testing}

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

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

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

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

## Использование {#ru_sdk_ui_and_core_android_use}

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

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

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

1.  Создать объект `EcmpPaymentInfo`.

    -   Этот объект должен содержать следующие обязательные параметры:
        -   `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay;
        -   `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта;
        -   `paymentCurrency` \(string\) — код валюты платежа в формате ISO-4217 alpha-3;
        -   `paymentAmount` \(integer\) — сумма платежа в дробных единицах валюты;
        -   `customerId` \(string\) — идентификатор пользователя в рамках проекта;
        -   `signature` \(string\) — подпись запроса, составленная после указания всех целевых параметров.
    -   Дополнительно могут использоваться и другие параметры, представленные [в следующей таблице](ru_sdk_ui_and_core_android.md#table_mhv_gqf_hvb).
    ```language-json
    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`.

    ```language-json
    ecmpPaymentInfo.signature = SignatureGenerator.generateSignature(
           paramsToSign = ecmpPaymentInfo.getParamsForSignature(),
           secret = SECRET_KEY
       )
    ```

3.  Создать объект `EcmpPaymentOptions`.

    -   Этот объект должен содержать следующие обязательные параметры:
        -   Для любых платежей —параметр `actionType`, в котором необходимо указать целевое действие: тип операции `Sale`, `Auth` или `Verify`;
        -   Для оплат с прямым использованием платёжных карт —параметр `CUSTOMER_EMAIL` или параметр `CUSTOMER_PHONE` объекта `additionalFields` \(по крайней мере один из них\) для отображения пользователю соответствующих полей на страницах платёжной формы.
    -   Для аутентификации 3‑D Secure рекомендуется указать следующие параметры со сведениями о платёжном адресе:

        -   `BILLING_COUNTRY` — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\);
        -   `BILLING_POSTAL` — индекс платёжного адреса пользователя;
        -   `BILLING_CITY` — название города платёжного адреса пользователя;
        -   `BILLING_ADDRESS` — название улицы платёжного адреса пользователя.
        Эти параметры указываются в объекте `additionalFields` и соответствующие поля отображаются пользователю на страницах платёжной формы.

        **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование таких параметров может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения.

    -   Дополнительно могут использоваться и другие параметры, представленные [в следующей таблице](ru_sdk_ui_and_core_android.md#table_g34_3h5_hvb)
    Следующий пример помимо обязательных для любых платежейобъекта `EcmpPaymentInfo` и параметра `actionType` содержит обязательныйдля оплат с прямым использованием платёжных карт параметр `CUSTOMER_EMAIL` и ряд дополнительных параметров, в том числе в объекте `additionalFields`.

    ```language-json
    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_FIRST_NAME
                value = "firstName"
              }
            }
    }
    ```

4.  Создать объект `EcmpPaymentSDK`.

    ```language-json
    val sdk = EcmpPaymentSDK(
            context = applicationContext,
            paymentOptions = paymentOptions,
           )
    ```

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

5.  Открыть платёжный интерфейс.

    ```language-json
    sdk.openPaymentScreen(this, 1234)
    ```


### Проведение платежей {#ru_sdk_ui_and_core_android_payments}

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

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

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

    ```language-java
    (EcmpPaymentOptions.EcmpActionType.Auth);
    ```

2.  Когда потребуется, подтвердить списание средств через Dashboard \([подробнее](ru_dbl_payments.md)\) или через Gate \(с помощью запроса к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture)\).

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

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

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

```language-java
(EcmpPaymentOptions.EcmpActionType.Verify);
```

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

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

```language-json
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` — возникла ошибка при проведении платежа.

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

#### Дополнение информации о платеже {#section_a2c_kvn_fvb .section}

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

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

#### Каскадное проведение платежей {#section_chg_3vn_fvb .section}

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

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

#### Сбор данных о пользователях {#section_xln_lvn_fvb .section}

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

#### Управление языком платёжного интерфейса {#section_mcq_5xc_xyb .section}

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

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

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

|Язык|Код|
|----|---|
|Английский|`en`|
|Испанский|`es`|
|Итальянский|`it`|
|Латышский|`lv`|
|Литовский|`lt`|
|Немецкий|`de`|
|Португальский|`pt`|
|Русский|`ru`|
|Украинский|`uk`|
|Французский|`fr`|
|Эстонский|`et`|

#### Сохранение платёжных данных {#section_ygy_gvn_fvb .section}

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

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

## Параметры вызова {#ru_sdk_ui_and_core_android_parameters}

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

|Код предварительно выбранного платёжного метода в соответствии [с таблицей](ru_pm_codes.md).

 Пример: `card`

|
|`ecmpThreeDSecureInfo`  
 object

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

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

 Пример: `IT`

|
|`regionCode  
`  
 string

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

 Пример: `IT`

|

В объекте `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

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

 Пример: `AB`

|

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

|Параметр|Описание|
|:-------|:-------|
|`type`  
 string

|Категория регистрируемой повторяемой оплаты.

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

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

|
|`period`  
 string

|Указатель базового периода списаний \(для регулярной оплаты\).

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

 -   `D` — ежедневно
-   `W` — еженедельно
-   `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\)
-   `Q` — ежеквартально
-   `Y` — ежегодно

|
|`expiry_day`  
 string

|Номер календарного дня, в который должна быть завершена повторяемая оплата\(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\)|
|`expiry_month`  
 string

|Порядковый номер месяца, в котором должна быть завершена повторяемая оплата\(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\)|
|`expiry_year`  
 integer

|Порядковый номер года, в котором должна быть завершена повторяемая оплата\(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\)|
|`scheduled_payment_id`  
 string

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

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

|
|`start_date`  
 string

|Дата первого списания\(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`|
|`time`  
 string

|Время выполнения последующих списаний\(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`|
|`schedule`  
 object — расписание проведения повторяемых оплат \(можно задать со стороны мерчанта\). Следует указать параметры `amount` и `date`

|
|`amount`  
 integer

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

|Дата списания в формате `ДД-ММ-ГГГГ`|

**Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения:

-   для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты;
-   для других доступных методов — значение соответствующего параметра согласно следующим правилам:
    -   для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\);
    -   для месяца — месяц регистрации повторяемой оплаты;
    -   для года — год, превышающий год регистрации повторяемой оплаты на 10 лет.

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

В объекте `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](references/ru/currencies/GBP.md)\)|
|`count`  
 integer

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

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

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

-   `Y` — адреса совпадают,
-   `N` — адреса не совпадают

|
|`billingRegionCode`  
 string

|Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма|
|`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](references/ru/countries/GB.md)\)|
|`deliveryEmail`  
 string

|Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов|
|`deliveryTime`  
 string

|Срок доставки.

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

-   `01` — электронная доставка в день покупки,
-   `02` — доставка в день покупки,
-   `03` — доставка на следующий день после покупки,
-   `04` — доставка более чем через один день после покупки

|
|`nameIndicator`  
 string

|Индикатор совпадения имени пользователя с именем получателя.

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

-   `01` — имена совпадают,
-   `02` — имена не совпадают

|
|`postal`  
 string

|Почтовый индекс доставки, не более шестнадцати символов|
|`regionCode`  
 string

|Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма. При указании значения этого параметра также необходимо указать значение параметра `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

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