SDK Core для Android

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

Введение

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

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

В этой статье представлена информация о работе с SDK Core для Android с описанием схемы взаимодействия, сценариев проведения платежей, а также дополнительных возможностей с примерами кода на языке Kotlin.

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

Возможности

SDK Core для Android поддерживает работу с платёжными картами, а также альтернативным методом Google Pay. Функционально SDK Core для Android позволяет:

  • Проводить оплаты с незамедлительным списанием средств.
  • Осуществлять блокировку средств для последующего списания по истечении заданного периода, либо на основании подтверждающего запроса (через интерфейсы Gate или Dashboard).
  • Выполнять проверку платёжных карт для их дальнейшего использования.
  • Регистрировать проведение повторяемых оплат.
  • Сохранять платёжные данные для проведения последующих оплат.

При проведении платежей от пользователей могут требоваться дополнительные действия, например прохождение аутентификации 3‑D Secure и указание сведений о владельце платёжного инструмента. Необходимость выполнения этих действий, как правило, зависит от протоколов и правил провайдеров и платёжных систем, но в отдельных случаях может зависеть и от предпочтений мерчанта. SDK Core для Android поддерживает работу со следующими процедурами и дополнительными возможностями:

  • Аутентификация 3‑D Secure — процедура аутентификации пользователей по протоколам 3‑D Secure.
  • Каскадное проведение платежей — дополнительные попытки проведения платежей (когда это актуально) без изменения способа оплаты.
  • Дополнение информации о платежах — процедура указания дополнительных данных, которые могут запрашиваться платёжными системами в некоторых случаях.
  • Сбор данных о пользователях — получение и предоставление дополнительной информации о пользователях, которая может быть актуальна при проведении последующих платежей.

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

Схема работы

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

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

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

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

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

  1. Решить организационные вопросы, касающиеся взаимодействия с ecommpay:

    1. Если у компании нет идентификатора и ключа для взаимодействия с ecommpay — отправить заявку на подключение.
    2. Если у компании есть идентификатор и ключ для взаимодействия с ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK Core для Android и согласовать порядок тестирования и запуска.
  2. Выполнить подготовительные технические работы:

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

    1. Для тестирования следует использовать идентификатор тестового проекта и данные тестовых карт.
    2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от ecommpay.

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

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

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

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

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

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

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

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

Для перехода в тестовый режим проведения платежей необходимо:

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

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

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

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

Сценарии, порядок выполнения целевых действий, а также набор параметров, доступных при работе с SDK Core для Android, представлены в следующих разделах этой статьи.

Порядок выполнения целевых действий

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

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

  1. Создать объект MSDKCoreSession.
    val config = MSDKCoreSessionConfig.debug("API HOST", "WS API HOST")
    val msdkSession = MSDKCoreSession(config)
  2. Создать объект PaymentInfo с параметрами проведения платежа. В объекте должен содержаться обязательный минимум параметров (идентификатор проекта, платежа и пользователя, а также сумма и валюта платежа), дополнительно также могут быть переданы и другие параметры (подробнее).
    val paymentInfo = PaymentInfo(  // информация о платеже
        projectId = 553,   // идентификатор проекта
        paymentId = "payment_21",   // идентификатор платежа
        paymentAmount = 400,        // сумма платежа
        paymentCurrency = "EUR",    // код валюты платежа
        customerId = "12"           // идентификатор пользователя
    )
  3. Получить строку для подписывания параметров и передать её в серверную часть приложения.
    paymentInfo.getParamsForSignature(),
  4. На стороне серверной части приложения подписать итоговый набор параметров и передать его в клиентскую часть.
  5. Добавить подпись в объект PaymentInfo.
  6. Отправить запрос на создание платёжной сессии. Для этого необходимо запустить выполнение метода getInitInteractor.
    val interactor = msdkSession.                                              
        InitRequest(paymentInfo, null, null),
        this
    )
  7. Принять уведомление с информацией о создании платёжной сессии, а также списками доступных платёжных методов и сохранённых платежных данных, актуальных для используемого проекта и конкретного пользователя.
    fun onInitReceived(
    paymentMethods: List<PaymentMethod>,
    savedAccounts: List<SavedAccount>
    ) {
    val stringResourceManager = msdkSession.getStringResourceManager()
    val title = stringResourceManager.payment.methodsTitle
     
    val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
    val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
     
    val paymentMethods = msdkSession.getPaymentMethods()  // получение списка платёжных методов
    val savedAccounts = msdkSession.getSavedAccounts()   // получение списка сохранённых платёжных данных
    }
  8. Обработать полученные данные и отобразить пользователю форму оплаты.
  9. Для проведения оплаты через Google Pay необходимо выполнить следующее:
    • Получить токен от Google Pay, для этого можно использовать класс GooglePayHelper. Подробная информация о настройке приложения для работы с Google Pay представлена в документации.
      val googlePayHelper = GooglePayHelper("merchant Id")
      val googleJson = googlePayHelper.createPaymentDataRequest(BigDecimal.valueOf(12.34), "USD").toString()
      val gpayRequest = PaymentDataRequest.fromJson(googleJson)
       
      val client = Wallet.getPaymentsClient(
          this,
          Wallet.WalletOptions.Builder()
              .setEnvironment(WalletConstants.ENVIRONMENT_TEST)// тестовая среда
              .setTheme(WalletConstants.THEME_LIGHT)
              .build()
      )
       
      AutoResolveHelper.resolveTask(
          client.loadPaymentData(gpayRequest),
          this,
          991
      )
    • Получить токен от Google Pay в уведомлении onActivityResult.
      override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
          super.onActivityResult(requestCode, resultCode, data)
          if (data == null) return
       
          val paymentData = PaymentData.getFromIntent(data)
          val paymentInformation = paymentData?.toJson() ?: return
          val paymentMethodData: JSONObject = JSONObject(paymentInformation).getJSONObject("paymentMethodData")
          val token = paymentMethodData.getJSONObject("tokenizationData").getString("token")
       
      }
  10. Отправить запрос на создание платежа с учётом полученных от пользователя данных. Для этого необходимо запустить выполнение метода getPayInteractor.
    // оплата с использованием карты
    interactor.execute(
                NewCardSaleRequest(          // сценарий
                    cvv = "123",             // код проверки подлинности карты
                    pan = "5555555555554444",   // номер карты
                    year = 2025,             // год окончания срока действия карты
                    month = 1,               // месяц окончания срока действия карты
                    cardHolder = "John Doe"  // фамилия и имя держателя карты
                ),
                this
            )
     
    // оплата с использованием метода Google Pay
    interactor.execute(
                GooglePaySaleRequest(            // сценарий
                    merchantId = merchant_321,   // идентификатор мерчанта
                    token = token,               // токен, полученный от Google Pay
                    environment = GooglePayEnvironment.TEST   // тестовая среда
                ),
                this
            )
  11. Принять ряд уведомлений от SDK Core для Android: о создании платежа и об изменении статуса платежа. Если актуально, также принять уведомления о необходимости дополнения информации о платеже и прохождения аутентификации с использованием протокола 3‑D Secure и выполнить требуемые действия.
  12. Принять уведомление с информацией о результате платежа и отобразить эту информацию пользователю.

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

Параметры работы с SDK Core для Android

Действия с платёжными картами

Для выполнения таких целевых действий с прямым использованием карт, как проведение оплат (NewCardSaleRequest), выполнение блокировок средств (CardAuthRequest) и проверок действительности карт (CardVerifyRequest), используются следующие наборы данных.

Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты (для проверки действительности необходимо указывать 0)
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • register (boolean) — признак регистрации повторяемых оплат, для которого необходимо использовать значение true. Информация о параметрах, доступных для регистрации повторяемых оплат представлена в отдельной статье
  • cvv (string) — код проверки подлинности карты
  • pan (string) — номер карты (без указания пробелов)
  • year (integer) — год окончания срока действия карты
  • month (integer) — месяц окончания срока действия карты
  • cardHolder (string) — имя держателя, указанное на карте
  • saveCard (boolean) — признак сохранения данных платёжной карты

Формирование токенов

SDK Core для Android поддерживает формирование токенов платёжных данных. При выполнении сценария формирования токенов (CardTokenizeRequest) не выполняется никаких финансовых операций, но создаётся безопасный идентификатор, ассоциированный с данными определённой платёжной карты. Информация о создании и использовании токенов представлена в соответствующих статьях: Формирование токенов и Проведение оплат по токенам.

Для формирования токенов через SDK Core для Android необходимы следующие наборы данных.

Создание платёжной сессии Формирование токена
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • pan (string) — номер карты (без указания пробелов)
  • year (integer) — год окончания срока действия карты
  • month (integer) — месяц окончания срока действия карты
  • cardHolder (string) — имя держателя, указанное на карте

Использование сохранённых платёжных данных

SDK Core для Android поддерживает возможности сохранения платёжных данных по инициативе пользователей и через формирование токенов, а также использования этих данных для проведения платежей. С использованием сохранённых платёжных данных и токенов можно проводить оплаты и выполнять блокировку средств через определённые сценарии. В случае с сохранёнными платёжными данными используются сценарии SavedCardSaleRequest (для оплат) и SavedCardAuthRequest (для блокировок), а в случае с токенами — CardSaleTokenizeRequest (для оплат) и CardAuthTokenizeRequest (для блокировок).

Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • account_token (string) — токен платёжных данных (используется для сценариев с участием токена)
  • cvv (string) — код проверки подлинности карты
  • accountId (integer) — идентификатор сохранённых платёжных данных, полученный в уведомлении о создании платёжной сессии

Оплаты с использованием альтернативных методов

SDK Core для Android поддерживает проведение оплат (GooglePaySaleRequest) и блокировку средств (GooglePayAuthRequest) с использованием метода Google Pay.

Чтобы проводить оплаты с использованием метода Google Pay, со стороны мерчанта предварительно необходимо:

  1. Зарегистрироваться в сервисе Google Pay Business Console и получить идентификатор мерчанта в сервисе Google Pay (Google merchant ID).
  2. Принять и соблюдать Правила допустимого использования Google Pay API, а также принять условия, приведённые в Пользовательском соглашении Google Pay API.
  3. Встроить в пользовательский интерфейс кнопку Google Pay, соблюдая рекомендации по правильному использованию бренда, и реализовать процесс получения токена с карточными данными пользователя от сервиса Google Pay.
  4. Добавить в файл AndroidManifest.xml следующую информацию:
    <meta-data
        android:name="com.google.android.gms.wallet.api.enabled"
        android:value="true" />
Создание платёжной сессии Создание платежа
  • project_id (integer) — идентификатор проекта, полученный от ecommpay
  • payment_id (string) — идентификатор платежа, уникальный в рамках проекта
  • payment_amount (integer) — сумма платежа в дробных единицах валюты
  • payment_currency (string) — код валюты платежа в формате ISO 4217 alpha-3
  • customer_id (string) — идентификатор пользователя, уникальный в рамках проекта
  • merchantId (string) — идентификатор мерчанта в сервисе Google Pay (Google merchant ID)
  • token — токен, полученный от Google Pay
  • environment — тестовый или реальный платёж (доступные значения: test и prod; при указании значения test, в запросе также должен использоваться идентификатор тестового проекта мерчанта, при указании prod — идентификатор рабочего проекта)
  • recepientInfo (используется для сценария GooglePayAuthRequest) — объект, содержащий сведения о пользователе; используется для оплат с целью погашения задолженностей

Использование дополнительных параметров

Кроме обязательного минимума параметров в запросах могут использоваться и дополнительные.

  • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
  • paymentDescription (string) — описание платежа.
  • regionCode (string) — код страны в формате ISO 3166 alpha-2.
  • token (string) — токен платёжных данных.
  • forcePaymentMethod (string) — код предварительно выбранного платежного метода. Коды платёжных методов доступны в справочнике.
  • hideSavedWallets (boolean) — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости не отображать пользователю сохранённые платёжные инструменты. Возможные значения:
    • true — сохранённые платёжные данные не отображаются пользователю.
    • false — сохранённые платёжные данные отображаются пользователю.

Дополнительные возможности

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

При работе с SDK Core для Android поддерживается сохранение платёжных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Сохранение платёжных данных может выполняться по инициативе пользователя при проведении оплат, либо через выполнение сценария формирования токена (CardTokenizeRequest). Возможность формирования токенов доступна в рамках проекта по умолчанию, а возможность сохранения платёжных данных по инициативе пользователя подключается отдельно. Для подключения возможности необходимо обратиться к специалистам технической поддержки ecommpay, а также обеспечить отображение в пользовательском интерфейсе переключателя для сохранения данных.

В результате сохранения платёжных данных по инициативе пользователя для каждого платёжного инструмента формируется идентификатор (account_id), ассоциированный с идентификатором конкретного пользователя (customer_id). В дальнейшем идентификаторы платёжных инструментов можно получить в уведомлении от SDK Core для Android о создании платёжной сессии и использовать в запросе на создание платежа.

Если сохранение платёжных данных выполнялось в результате выполнения сценария CardTokenizeRequest, для конкретной платёжной карты пользователя формируется токен, который можно получить в уведомлении о формировании токена в объекте Payment и в дальнейшем указывать этот токен в запросах на проведение платежей. Для выполнения сценария формирования токена в запросе на создание сессии в SDK Core для Android со стороны мерчанта необходимо указать идентификаторы проекта и пользователя, остальные данные для формирования токена (номер и срок действия платёжной карты, а также имя держателя карты) — запросить у пользователя.

Рис.: Пример сохранённых платёжных данных

"SavedAccounts":
{
  "number": "555555******4444",
  "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // токен платёжных данных
  "id": 12353661,   // идентификатор сохранённых платёжных данных (accountId)
  "last_deposit_date": "2022-04-22 06:22:33",
  "last_tokenize_date": null,
  "type": "card",
  "additional": {
    "email": "john@example.com",
    "phone": "+79012345678",
    "country": "RU",
    "recurring_enable": false,
    "card": {
      "holder": "Jonh Doe",
      "country": "RU",
      "bank_name": "CIAGROUP",
      "type": "mastercard",
      "product_name": "PREPAID",
      "expiry": "02/24"
    }
  },

Аутентификация 3‑D Secure

В случаях, когда для проведения платежей требуется выполнить аутентификацию пользователей по протоколам 3‑D Secure, со стороны мерчанта необходимо:

  1. Принять от SDK Core для Android уведомление onThreeDSecure о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект acsPage с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации.
  2. Отобразить пользователю страницу аутентификации.
  3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод threeDSecureHandled.
func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment)
{
    interactor.threeDSecureHandled()    // вызов метода
}

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

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

Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK Core для Android поступает уведомление, в котором содержится объект isCascading со значением true, что означает, что в рамках каскадного проведения платежей доступно выполнение дополнительной попытки. Если для проведения платежа необходима аутентификация пользователя, со стороны мерчанта требуется отобразить пользователю информацию об ошибке, получить от него подтверждение о выполнении очередной попытки и повторить проведение платежа. Если аутентификация не требуется, дополнительные действия со стороны мерчанта не выполняются.

func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment)
{
    interactor.threeDSecureHandled()  
}

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

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

Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список параметров, актуальных для конкретного платежа поступает в уведомлении от SDK Core для Android после отправки запроса на создание платежа (GetPayInteractor). Со стороны мерчанта необходимо обеспечить отображение пользователю полей для заполнения запрашиваемых данные, а затем передать полученные значения к SDK Core для Android.

override fun onClarificationFields(clarificationFields: List<ClarificationField>, payment: Payment) { // получение списка запрашиваемых данных
    interactor.sendClarificationFields(clarificationFields) // передача полученных от пользователя данных
}

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

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

После получения от SDK Core для Android уведомления со списком запрашиваемых параметров со стороны мерчанта необходимо отобразить пользователю в форме оплаты поля для заполнения. Далее полученные значения необходимо передать к SDK Core для Android и продолжить проведение платежа.

override fun onCustomerFields(customerFields: List<CustomerField>) {  // получение списка запрашиваемых данных
    interactor.sendCustomerFields(customFields) // передача полученных от пользователя данных
}

Приём уведомлений

Информирование о платёжной сессии

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

  • onInitReceived — создание платёжной сессии в платёжной платформе ecommpay.
    override fun onInitReceived() {
        val stringResourceManager = msdkSession.getStringResourceManager()
        val title = stringResourceManager.payment.methodsTitle
      
        val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager()
        val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa")
      
        val paymentMethods = msdkSession.getPaymentMethods()
        val savedAccounts = msdkSession.getSavedAccounts()
    }
  • onPaymentRestored — создание платёжной сессии с идентификатором платежа, который использовался ранее. Если платежу ещё не присвоен итоговый статус, можно использовать метод PaymentRestoreRequest и продолжить проведение инициированного ранее платежа.
    override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.activity_payment_restore)
            progressDialog = ProgressDialog(this@PaymentRestoreActivity)
            progressDialog.setMessage("Payment restoring")
            progressDialog.setCancelable(false)
            progressDialog.show()
    
            interactor.execute(PaymentRestoreRequest(), this)
        }
  • onError — возникла ошибка.
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")

Информирование о платеже

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

  • onPaymentCreated — создание платежа.
  • onStatusChanged — изменение статуса платежа.
  • onCustomerFields — необходимость в указании дополнительных данных о пользователе.
  • onThreeDSecure — необходимость в выполнении аутентификации по протоколу 3‑D Secure.
  • onClarificationFields — необходимость в дополнении информации о платеже.
  • onCompleteWithSuccess — платёж проведён.
  • onCompleteWithFail — получен отказ в проведении платежа.
  • onCompleteWithDecline — платёж отклонён.
  • onError — возникла ошибка.
    override fun onError(code: "Network & Server API", 
    message: "{"status":"validation","code":"501",
    "errors":{"sid":"Make payment before check status"}}")

Реагирование на ошибки

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

Ошибка Возможная причина Рекомендуемые действия
CLARIFICATION_FIELDS_ERROR В рамках выполнения процедуры дополнения информации о платеже переданы некорректные данные Повторить заполнение дополнительных данных
CUSTOMER_ID_NOT_EXIST В запросе на формирование токена или проверку действительности платёжной карты не передан обязательный параметр customerId Скорректировать запрос
ILLEGAL_ARGUMENTS В запросе переданы некорректные значения Скорректировать запрос
INTERACTOR_NOT_RUNNING Выполнение действия, доступного в рамках проведения платежа, до его инициирования (например, передача дополнительных данных о пользователе до отправки запроса на создание платежа) Отправить запрос на создание платежа
NETWORK_ERROR Ошибка соединения Следует связаться со специалистами технической поддержки
NETWORK_IS_NOT_AVAILABLE Сеть недоступна Повторить запрос позже
NETWORK_TIMEOUT Выполнение запроса отклонено из-за превышения допустимого времени ожидания Повторить запрос позже
PAYMENT_ALREADY_EXIST Выполнение запроса отклонено из-за указания идентификатора платежа, который уже использовался ранее Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса
PAYMENT_HAS_FINAL_STATUS Выполнение запроса отклонено из-за указания в запросе идентификатора платежа, которому уже присвоен итоговый статус Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса
PAYMENT_METHOD_NOT_AVAILABLE Выполнение запроса отклонено из-за указания в запросе платёжного метода, недоступного в рамках используемого проекта Указать доступный в рамках проекта платёжный метод и повторить отправку запроса
PAYMENT_NOT_FOUND Не найден объект Payment Повторить выполнение запроса. В случае возникновения ошибки обратиться к специалистам технической поддержки.
PAYMENT_TOKEN_NOT_EXIST В запросе на проведение оплаты или проверки действительности платёжной карты с использованием токена не передан токен платёжных данных Указать токен платёжных данных и повторить отправку запроса
SERVER_API_ERROR Ошибка на стороне SDK Core для Android Следует связаться со службой технической поддержки
SESSION_NOT_INITIALIZED Выполнение запроса отклонено из-за попытки выполнить какой-либо сценарий до создания платёжной сессии Инициировать создание платёжной сессии (InitInteractor)
SERVER_CONTENT_PARSING_ERROR Не удалось преобразовать ответ от сервера Скорректировать запрос
SERVER_METHOD_NOT_FOUND Вызов метода, который не предусмотрен для работы с SDK Core для Android Скорректировать запрос
SERVER_UNAUTHORIZED Возникла ошибка соединения Повторить запрос позже