SDK для Android

SDK для Android — это набор средств разработки для подключения мобильных приложений, работающих на платформе Android, к платёжной платформе ECommPay. В этом разделе представлена информация о работе с SDK для Android с примерами кода на языках программирования Java и Kotlin.

Прим.: Представленная в этом разделе информация актуальна для SDK для Android версии 1.9.0 и выше. Сведения о работе с SDK для Android более ранних версий содержатся в разделе ru_sdk_android_old.html#ru_sdk_android_old.

SDK для Android может встраиваться в мобильные приложения, работающие на платформе Android версии 4.4 (уровень API — 19) или выше и поддерживающие AndroidX. Для корректного отображения платёжной формы разрешение экрана мобильного устройства должно быть не менее 480x800 пикселей.

Для SDK для Android версии 1.10.0 и выше подключение библиотек осуществляется через MavenCentral (подробнее). Также SDK для Android можно загрузить с GitHub по следующим ссылкам:

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

Возможности

SDK для Android позволяет проводить платежи с использованием платёжных карт, а также альтернативных платёжных методов. Для платежей с использованием карт доступны проведение разовых и повторяемых оплат, проверка действительности карт (подробнее). Среди поддерживаемых альтернативных платёжных методов доступны следующие:

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

При работе с SDK для Android используется платёжная форма ECommPay, в рамках работы с которой доступны следующие возможности:
  • Поддержка русского и английского языков (русского — при его выборе в настройках мобильного устройства и английского — в остальных случаях; со стороны мерчанта также возможно выбрать язык платёжной формы).
  • Поддержка индивидуального дизайна и настройка цветового оформления платёжной формы (подробнее).
  • Поддержка разных способов ввода данных карты (подробнее):
    • вручную,
    • сканируя карту,
    • выбирая сохранённую карту,
    • используя предварительно выбранную карту.
  • Сбор или указание дополнительных данных о пользователе (подробнее).
  • Уточнение дополнительных параметров, обязательных для проведения оплаты (подробнее).
  • Поддержка аутентификации 3‑D Secure 2. Протокол 3‑D Secure 2 является новой версией протокола 3‑D Secure (Three-Domain Secure), который обеспечивает безопасное проведение интернет-оплат с использованием платёжных карт (подробнее).
  • Поддержка повторных попыток оплаты в случае ошибок (подробнее).
  • Получение информации о платеже: на всех страницах платёжной формы доступна кнопка информации, при выборе которой отображаются данные о сумме, идентификаторе и дате проведения платежа, а также описание платежа.
  • Отправка электронного товарного чека пользователю (подробнее).

Состав

SDK для Android содержит файл с библиотеками ecommpaySDK.aar и примеры работы на языках программирования Java и Kotlin.

Схема работы

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

  1. В клиентской части мобильного приложения формируется объект с необходимыми параметрами для проведения платежа.
  2. В серверной части мобильного приложения вычисляется подпись на основании параметров платежа.
  3. В клиентской части формируется итоговый запрос на проведение платежа и с помощью библиотеки отправляется в платёжную платформу ECommPay.
  4. В платёжной платформе выполняется обработка платежа.
  5. От платёжной платформы к клиентской части отправляется результат выполнения платежа.
  6. От платёжной платформы на заданный URL отправляется оповещение.

Рис.: Схема взаимодействия



Подключение и использование

Для использования SDK для Android необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с ECommPay:
    • Если у компании нет идентификатора и ключа для взаимодействия с ECommPay — отправить заявку на подключение.
    • Если у компании есть идентификатор и ключ для взаимодействия с ECommPay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Android и согласовать с ними порядок тестирования и запуска.
  2. Выполнить подготовительные технические работы:
    1. Обеспечить подписывание данных на стороне серверной части мобильного приложения.
    2. Скачать и подключить SDK для Android.
    3. Доработать клиентскую часть мобильного приложения для инициирования платежей необходимых типов и обработки результатов этих платежей.
  3. Протестировать и запустить в работу обновлённое приложение.
    1. Для тестирования следует использовать тестовый идентификатор проекта и данные тестовых карт, предоставленные специалистами технической поддержки ECommPay.
    2. Для перевода в рабочий режим следует изменить тестовое значение идентификатора проекта на рабочее значение, полученное от ECommPay.

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

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

Рис.: Отображение списка доступных платёжных методов



Рис.: Оплата с использованием альтернативного платёжного метода DOKU



Рис.: Проверка действительности карты



Рис.: Выбор сохранённой карты



Рис.: Генерация токена карты



Рис.: Использование предварительно выбранной карты



Рис.: Уточнение дополнительных параметров, обязательных для проведения оплаты



Рис.: Возможность повторных попыток оплаты в случае ошибок



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

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

Рис.: Процесс подписывания данных



Получив строку для подписывания, необходимо выполнить следующие действия:
  1. Вычислить код HMAC для полученной строки на основе алгоритма SHA-512 и секретного ключа.
  2. Выполнить кодировку результата по алгоритму Base64.
Для проверки результата подписывания в серверной части приложения можно использовать следующий пример:
  • Строка для подписывания.
    customer_id:5;payment_amount:30;payment_currency:RUB;payment_id:payment1;project_id:115
  • Значение секретного ключа — 12345.
  • Результат генерации подписи.
    pVmAtGFBQJD2NgLToP1B2elR4QROiYGi3IobPD9PFDfrkjBqdSCFgrVSEtebVJUzOUUHX5tPnHQq9RMn61679A==

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

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

Подключение библиотек к проекту

Для подключения библиотек к проекту мобильного приложения необходимо:
  1. Загрузить файл ecommpaySDK.aar.
  2. Добавить в проект библиотеки из загруженного файла. В Android Studio 3.0 для этого необходимо перейти в раздел File > New > New Module, выбрать Import .JAR/.AAR Package и указать расположение файла ecommpaySDK.aar.
  3. Открыть файл модуля приложения (build.gradle).
  4. Добавить параметры компиляции в секцию android {}:
    compileOptions {
                    sourceCompatibility JavaVersion.VERSION_1_8
                    targetCompatibility JavaVersion.VERSION_1_8
                    }
  5. Добавить зависимости в секцию dependencies {}, если они не содержатся в этой секции.
    implementation project(path: ':ecommpaySDK')
     
    implementation 'io.card:android-sdk:5.5.1'
     
    implementation 'com.squareup.retrofit2:retrofit:2.3.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:3.10.0'
    implementation 'androidx.appcompat:appcompat:1.0.0'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.recyclerview:recyclerview:1.0.0'
    
    implementation 'com.squareup.retrofit2:converter-gson:2.3.0'
    implementation 'com.google.code.gson:gson:2.8.4'
    
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
    
    implementation 'androidx.lifecycle:lifecycle-viewmodel:2.0.0'
    implementation 'androidx.lifecycle:lifecycle-extensions:2.0.0'
    annotationProcessor 'androidx.lifecycle:lifecycle-compiler:2.0.0'
  6. Добавить разрешения в файл манифеста AndroidManifest.xml.
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

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

Для SDK для Android версии 1.10.0 и выше поддерживается подключение библиотек через MavenCentral. Для подключения библиотек через MavenCentral необходимо:
  1. Открыть файл модуля приложения (build.gradle).
  2. Указать в секции repositories {} репозиторий mavenCentral:
allprojects {
    repositories {
        google()
        jcenter()
        mavenCentral()
    }
}

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

Вызов в Java

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

  1. Создать объект ECMPPaymentInfo. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectID — идентификатор проекта, полученный от ECommPay при интеграции;
    • paymentID — идентификатор платежа, уникальный в рамках проекта;
    • paymentAmount — сумма платежа в минорных единицах;
    • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.

    Пример объекта ECMPPaymentInfo, который содержит только обязательные параметры:

    ECMPPaymentInfo paymentInfo = new ECMPPaymentInfo(
                   115, // идентификатор проекта, полученный от ECommPay при интеграции
                   "internal_payment_id_1", // идентификатор платежа, уникальный в рамках проекта
                   1999, // сумма платежа в минорных единицах
                   "USD" // валюта платежа в формате ISO-4217 alpha-3
                   );
    Дополнительно могут использоваться следующие объекты и параметры:
    • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
    • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
    • customerID — идентификатор пользователя, уникальный в рамках проекта.
    • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
    • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
    • token — токен карты.
    • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды поддерживаемых платёжных методов на Payment Page.
    • hideSavedWallets — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости скрывать сохранённые платёжные инструменты в платёжной форме. Возможные значения:
      • true — сохранённые ранее платёжные инструменты скрыты, они не отображаются при открытии платёжной формы.
      • false — сохранённые ранее платёжные инструменты отображаются при открытии платёжной формы.
    • ECMPScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать её. В объекте возможно передавать следующие параметры:
      • hide_success_final_page — финальная страница с сообщением о совершённом платеже не отображается в платёжной форме,
      • hide_decline_final_page — финальная страница с сообщением об отклонённом платеже не отображается в платёжной форме.

      Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

      // Init ECMPPaymentInfo
       
      paymentInfo.addEcmpScreenDisplayMode("hide_success_final_page")
                 .addEcmpScreenDisplayMode("hide_decline_final_page");
    Пример объекта ECMPPaymentInfo, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):
    ECMPPaymentInfo paymentInfo = new ECMPPaymentInfo(
                      115, // идентификатор проекта, полученный от ECommPay при интеграции
                      "internal_payment_id_1", // идентификатор платежа, уникальный в рамках проекта
                      1999, // сумма платежа в минорных единицах
                      "USD" // валюта платежа в формате ISO-4217 alpha-3
                      "T-shirt with dog print", // описание платежа
                      "10", // идентификатор пользователя, уникальный в рамках проекта
                      "US" // код страны в формате ISO 3166 alpha-2
                       );
  2. Получить строку для подписывания указанных параметров.
    paymentInfo.getParamsForSignature();
  3. Передать сгенерированную строку в серверную часть приложения.
  4. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  5. Добавить подпись в объект paymentInfo.
    paymentInfo.setSignature(signature);
  6. Вызвать платёжную форму.
    startActivityForResult(ECMPActivity.buildIntent(this,
                        paymentInfo),
                        PAY_ACTIVITY_REQUEST);

Вызов в Kotlin

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

  1. Создать объект ECMPPaymentInfo. Этот объект должен содержать обязательные параметры для открытия платёжной формы:
    • projectID — идентификатор проекта, полученный от ECommPay при интеграции;
    • paymentID — идентификатор платежа, уникальный в рамках проекта;
    • paymentAmount — сумма платежа в минорных единицах;
    • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.

    Пример объекта ECMPPaymentInfo, который содержит только обязательные параметры:

    val paymentInfo = ECMPPaymentInfo(
                        115, // идентификатор проекта, полученный от ECommPay при интеграции
                        "internal_payment_id", // идентификатор платежа, уникальный в рамках проекта
                        1999, // сумма платежа в минорных единицах
                        "USD") // валюта платежа в формате ISO-4217 alpha-3
    Дополнительно могут использоваться следующие объекты и параметры:
    • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
    • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
    • customerID — идентификатор пользователя, уникальный в рамках проекта.
    • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
    • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
    • token — токен карты.
    • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды поддерживаемых платёжных методов на Payment Page.
    • hideSavedWallets — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости скрывать сохранённые платёжные инструменты в платёжной форме. Возможные значения:
      • true — сохранённые ранее платёжные инструменты скрыты, они не отображаются при открытии платёжной формы.
      • false — сохранённые ранее платёжные инструменты отображаются при открытии платёжной формы.
    • ECMPScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать её. В объекте возможно передавать следующие параметры:
      • hide_success_final_page — финальная страница с сообщением о совершённом платеже не отображается в платёжной форме,
      • hide_decline_final_page — финальная страница с сообщением об отклонённом платеже не отображается в платёжной форме.

      Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

      // Init ECMPPaymentInfo
       
      paymentInfo.addEcmpScreenDisplayMode("hide_success_final_page")
                 .addEcmpScreenDisplayMode("hide_decline_final_page");
    Пример объекта ECMPPaymentInfo, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):
    val paymentInfo = ECMPPaymentInfo(
                       115, // идентификатор проекта, полученный от ECommPay при интеграции
                       "internal_payment_id", // идентификатор платежа, уникальный в рамках проекта
                       1999, // сумма платежа в минорных единицах
                       "USD", // валюта платежа в формате ISO-4217 alpha-3
                       "T-shirt with dog print", // описание платежа
                       "10", // идентификатор пользователя, уникальный в рамках проекта
                       "US")  // код страны в формате ISO 3166 alpha-2
  2. Получить строку для подписывания указанных параметров.
    paymentInfo.getParamsForSignature();
  3. Передать сгенерированную строку в серверную часть приложения.
  4. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть.
  5. Добавить подпись в объект paymentInfo.
    paymentInfo.signature = signature
  6. Вызвать платёжную форму.
    startActivityForResult(
                        ECMPActivity.buildIntent(this,
                        paymentInfo),
                        PAY_ACTIVITY_REQUEST)

Приём результатов

Для получения кода ответа о проведении платежа необходимо переопределить метод onActivityResult в том окне (activity), где вызывается ECMPActivity.

Рис.: Приём результатов в Java

@Override
 protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
     super.onActivityResult(requestCode, resultCode, data);
     if (requestCode == PAY_ACTIVITY_REQUEST) {
         switch (resultCode) {
             case ECMPActivity.RESULT_SUCCESS:
                 // В случае успешной оплаты
             case ECMPActivity.RESULT_CANCELLED:
                 // В случае отмены оплаты пользователем
             case ECMPActivity.RESULT_DECLINE:
                 // В случае получения общей ошибки
             case ECMPActivity.RESULT_FAILED:
                 // В случае получения внутренней ошибки
                 break;
         }
 
         if(data != null && data.hasExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR)) {
            String error = data.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR);
         }
 
         if(data != null && data.hasExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN)) {
             String token = data.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN);
         }
     }
 }

Рис.: Приём результатов в Kotlin

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
      super.onActivityResult(requestCode, resultCode, data)
      if(requestCode == PAY_ACTIVITY_REQUEST) {
          when (resultCode) {
              ECMPActivity.RESULT_SUCCESS -> {}   // В случае успешной оплаты
              ECMPActivity.RESULT_CANCELLED -> {} // В случае отмены оплаты пользователем
              ECMPActivity.RESULT_DECLINE -> {}   // В случае получения общей ошибки
              ECMPActivity.RESULT_FAILED -> {}   // В случае получения внутренней ошибки
          }
 
          val error = data?.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_ERROR)
          val token = data?.getStringExtra(ECMPActivity.DATA_INTENT_EXTRA_TOKEN)
      }
  }
Табл. 1. Допустимые коды ответов
Код результата Константа результата Значение Описание
0 RESULT_SUCCESS Success Платёж проведён
100 RESULT_DECLINE General decline Проведение платежа отклонено из-за получения общей ошибки от платёжной платформы
301 RESULT_CANCELLED Cancelled Проведение платежа отменено пользователем
501 RESULT_FAILED Internal error Возникла внутренняя ошибка

Обработка оповещений

Обзор

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

{
    "payment": {
        "status": "success",
        "type": "purchase",
        "id": "12345",
        "date": "2020-09-11T14:49:18+0000",
        "method": "card",
        "sum": 1000,
        "currency": "USD"
         }
}

Далее представлена информация об этих оповещениях.

Оповещения платёжной платформы

При проведении платежа платёжная платформа отправляет оповещения на указанный URL. Этот URL необходимо сообщить службе технической поддержки ECommPay. Подробная информация об оповещениях представлена в разделе Оповещения.

Оповещения SDK для Android

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

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

  1. Создать приёмник широковещательных сообщений — объект BroadcastReceiver.
  2. При поступлении в BroadcastReceiver широковещательных сообщениях от SDK для Android, с помощью ключа ECPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.getValue() получать из объекта Intent информацию о платеже. Ключ представляет собой константу, предоставляемую ECMPActivity.

Далее представлены примеры реализации BroadcastReceiver для получения информации о результате проведения платежа.

Рис.: Java

class YourClass {   
    private BroadcastReceiver mReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            ECMPPaymentData paymentData = intent.getParcelableExtra(ECMPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.getValue());
        }
    };
}

Рис.: Kotlin

class YourClass {  
    private val mReceiver: BroadcastReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val paymentData: ECMPPaymentData = intent.getParcelableExtra(ECMPCallbackType.ECMP_CALLBACK_PAYMENT_RESULT.value)
        }
    }
}

Управление платёжными данными

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

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

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

Для обеспечения возможности сохранения данных карты и проведения оплаты по сохранённым данным пользователя в объект ECMPPaymentInfo необходимо добавить параметр customerID, который позволяет привязать список карт к определённому пользователю на стороне платёжной платформы. При проведении данного типа платежей SDK для Android отправляет запрос в платёжную платформу на получение списка сохранённых карт пользователя и при наличии таковых выводит их на платёжной форме. Если пользователь исключает карту из списка сохранённых, то SDK для Android отправляет запрос в платёжную платформу на удаление данных из списка сохранённых платёжных инструментов.

Оплата с использованием токенов

SDK для Android предоставляет возможность проводить платежи по токену карты. В этом случае на стороне серверной части приложения необходимо обеспечить хранение данных карты пользователя и её токена. Если заданный токен соответствует карте пользователя, то при проведении оплаты пользователю отображается форма оплаты с предварительно выбранной картой и заполненными данными этой карты, кроме CVV.

При использовании токена для проведения оплат параметр token должен быть включён в список параметров для подписывания.

Для оплаты по токену необходимо задать токен в объекте paymentInfo:

paymentInfo.setToken(token);

Автоматическая генерация токена

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

Рис.: Фрагмент оповещения с токеном

"account": {
            "number": "546942******3838",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Генерация токена по запросу

Другим способом генерации токена является отправка запроса на генерацию токена. Для генерации токена необходимо задать Tokenize в типе действия:

Рис.: Java

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize);

Рис.: Kotlin

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize)

Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена.

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

Базовый вариант оплаты

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

Разовая двухстадийная оплата

Для проведения разовых двухстадийных оплат необходимо:
  1. Задать значение Auth в типе действия.

    Рис.: Java

    paymentInfo.setAction(ECMPPaymentInfo.ActionType.Auth);

    Рис.: Kotlin

    paymentInfo.setAction(ECMPPaymentInfo.ActionType.Auth)
  2. Подтвердить списание средств через Old Dashboard или с помощью запроса на /v2/payment/card/capture.

Подробная информация о проведении оплат с предварительной блокировкой представлена в разделе Блокировка средств.

Повторяемая оплата

SDK для Android поддерживает проведение повторяемых оплат. Такие оплаты бывают трёх типов: OneClick, автооплаты и регулярные оплаты. Подробнее о повторяемых оплатах — в разделе Общая информация.

Для проведения повторяемой оплаты необходимо:
  1. Создать объект ECMPRecurrentInfo.

    Рис.: Java

    ECMPRecurrentInfo recurrentInfo = new ECMPRecurrentInfo(
                     "R", // тип повторяемой оплаты
                     "20", // день окончания действия подписки
                     "11", // месяц окончания действия подписки
                     "2020", // год окончания действия подписки
                     "M", // периодичность проведения повторяемых оплат
                     "12:00:00", // время проведения повторяемых оплат
                     "12-02-2019", // дата проведения первой повторяемой оплаты
                     "your_recurrent_id"); // идентификатор повторяемой оплаты в проекте

    Рис.: Kotlin

    val recurrentInfo = ECMPRecurrentInfo(
                     "R", // тип повторяемой оплаты
                     "20", // день окончания действия подписки
                     "11", // месяц окончания действия подписки
                     "2020", // год окончания действия подписки
                     "M", // периодичность проведения повторяемых оплат
                     "12:00:00", // время проведения повторяемых оплат
                     "12-02-2019", // дата проведения первой повторяемой оплаты
                     "your_recurrent_id"); // идентификатор повторяемой оплаты в проекте
  2. Дополнительно можно задать:

    • Сумму списания. По умолчанию сумма списания равна сумме платежа. Задать другую сумму списания можно в объекте recurrentInfo:

      Рис.: Java

      recurrentInfo.setAmount(1000);

      Рис.: Kotlin

      recurrentInfo.setAmount(1000)
    • Дат и сумм списания. По умолчанию при повторяемых оплатах средства списываются с карты строго фиксированно по времени и сумме, но можно задать собственное расписание в объекте recurrentInfo:

      Рис.: Java

      recurrentInfo.setSchedule(new ECMPRecurrentInfoSchedule[]{
                     new ECMPRecurrentInfoSchedule("10-10-2020",1200),
                     new ECMPRecurrentInfoSchedule("10-11-2020",1000),
                     .....
      });

      Рис.: Kotlin

      recurrentInfo.setSchedule(arrayOf(ECMPRecurrentInfoSchedule("10-10-2020",1200),
                                        ECMPRecurrentInfoSchedule("10-11-2020",1000),
                                        .....
      ))
  3. Добавить объект ECMPRecurrentInfo в объект ECMPPaymentInfo.

    Рис.: Java

    paymentInfo.setRecurrent(recurrentInfo);

    Рис.: Kotlin

    paymentInfo.setRecurrent(recurrentInfo)

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

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

Для проведения верификации карты необходимо задать Verify в типе действия:

Рис.: Java

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify);

Рис.: Kotlin

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify)

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

SDK для Android поддерживает проведение оплат с использованием альтернативных платёжных методов: Google Pay, Skrill Wallet, DOKU Wallet, «QIWI Кошелёк», Banks of Malaysia, Banks of Thailand, «Оплата в магазинах Таиланда», MCash Wallet, Alipay, Neteller, WebMoney (сценарии оплат WebMoneyLight и WebMoneyClassic). В большинстве случаев пользователь перенаправляется к сервису платёжного метода для завершения оплаты. Описание каждого из этих методов представлено в отдельной статье, а далее также приведено описание особенностей работы с методом Google Pay и поддерживаемыми сценариями оплат метода WebMoney.

Схема взаимодействия (для случая с перенаправлением) представлена далее.

Рис.: Проведение оплаты с использованием альтернативных платёжных методов (АПМ)



Для проведения платежей с использованием альтернативных платёжных методов требуется связаться со специалистами службы технической поддержки ECommPay для включения данной возможности в рамках проекта. Также можно настроить передачу данных о пользователе (подробнее).

Google Pay

Чтобы обеспечить возможность проведения оплат с использованием метода Google Pay, со стороны мерчанта предварительно необходимо:
  1. Зарегистрироваться в сервисе Google Pay Business Console и получить идентификатор мерчанта в сервисе Google Pay (Google merchant ID).
  2. Принять и соблюдать Правила допустимого использования Google Pay API, а также принять условия, приведённые в Пользовательском соглашении Google Pay API.
  3. Связаться со специалистами технической поддержки ECommPay для подключения метода Google Pay в рамках требуемых проектов.

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

  • В запросах на открытие платёжной формы необходимо указывать идентификатор мерчанта в сервисе Google Pay (merchantId) и объект PaymentDataRequest, который используется для подключения приложения мерчанта к Google Pay API и описан в документации Google Pay API.

    Рис.: Пример объекта PaymentDataRequest

    {
      "apiVersion": 2,
      "apiVersionMinor": 0,
      "merchantInfo": {
        "merchantName": "Example Merchant",
        "merchantId": "merchant_id"
      },
      "allowedPaymentMethods": [
        {
          "type": "CARD",
          "parameters": {
            "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
            "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"]
          },
          "tokenizationSpecification": {
            "type": "PAYMENT_GATEWAY",
            "parameters": {
              "gateway": "ecommpay",
              "gatewayMerchantId": "gateway_merchant_id"
            }
          }
        }
      ],
      "transactionInfo": {
        "totalPriceStatus": "FINAL",
        "totalPrice": "12.34",
        "currencyCode": "USD"
      }
    }
    Необходимо учесть, что в объекте PaymentDataRequest.transactionInfo должны использоваться следующие параметры:
    • totalPriceStatus — статус итоговой суммы платежа; должно передаваться значение FINAL, подтверждающее, что итоговая сумма платежа соответствует сумме, отображённой пользователю;
    • totalPrice — сумма платежа в дробных единицах валюты; эта сумма должна соответствовать сумме, указанной в объекте PaymentDataRequest.PaymentInfo;
    • currencyCode — код валюты платежа в формате ISO-4217 alpha-3.

    Далее представлены примеры данных из запросов на открытие платёжной формы, содержащих идентификатор мерчанта merchantId и объект PaymentDataRequest.

    Java

    {
    PaymentInfo paymentInfo = PaymentInfo()
    ...
    PaymentDataRequest paymentDataRequest = generatePaymentRequest();
    paymentInfo.setPaymentDataRequest(paymentDataRequest);
    paymentInfo.setMerchantId("your merchant id");
    ...
    }
     
    private PaymentDataRequest generatePaymentRequest() {
        return PaymentDataRequest.fromJson(
    "your json object");
    }

    Kotlin

    {
    val paymentInfo = PaymentInfo()
    ...
    val paymentDataRequest = generatePaymentRequest();
    paymentInfo.setPaymentDataRequest(paymentDataRequest);
    paymentInfo.setMerchantId("your merchant id");
    ...
    }
     
    private fun generatePaymentRequest() -> PaymentDataRequest {
        return PaymentDataRequest.fromJson(
    "your json object");
    }
  • Для использования метода Google Pay в качестве предварительно выбранного необходимо передать параметр forcePaymentMethod со значением google_pay_host. При этом отображение кнопки метода Google Pay в приложении мерчанта необходимо настроить в соответствии с фирменным стилем Google.

WebMoney

При работе с SDK для Android поддерживается проведение оплат с использованием сценариев WebMoneyLight и WebMoneyClassic. При использовании WebMoneyLight осуществляется перенаправление пользователя к форме оплаты WebMoney для перевода средств на WM-кошелёк мерчанта. При использовании WebMoneyClassic пользователь самостоятельно переходит в сервис WebMoney для проведения оплаты. Все основные процедуры, такие как вызов платёжной формы, приём результатов и обработка оповещений, выполняются так же, как и при работе с другими платёжными методами, а при формировании запросов необходимо учитывать следующее:

  • Для сценария оплаты WebMoneyClassic поддерживается возможность автоматического инициирования оплаты без указания пользователем данных в платёжной форме. Для этого, помимо базового минимального набора параметров (подробнее: Вызов платёжной формы), мерчанту необходимо передать в запросе на открытие платёжной формы значения обоих следующих параметров:
    • accountNumber — идентификатор пользователя в сервисе WebMoney (WMID).
    • accountPurseType — тип кошелька WebMoney.

    Если в запросе переданы значения обоих указанных параметров, проведение оплаты инициируется автоматически без возможности для пользователя изменить указанные данные.

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

  • При проведении платежа необходимо использовать валюту, которая поддерживается методом WebMoney. Информация о поддерживаемых валютах представлена в разделе WebMoney.

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

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

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

Рис.: Java

paymentInfo.setECMPAdditionalFields(new ECMPAdditionalField[]{
     new ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.customer_first_name, "Mark"),
     new ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.billing_country, "US"),
     ECMPAdditionalField(aps_account_number, ""),
     ECMPAdditionalField(aps_account_security_code, "")
     .....
});

Рис.: Kotlin

paymentInfo.ecmpAdditionalFields = arrayOf(ECMPAdditionalField(
             ECMPAdditionalField.AdditionalFieldType.customer_first_name, "Mark"),
             ECMPAdditionalField(ECMPAdditionalField.AdditionalFieldType.billing_country, "US"),
             ECMPAdditionalField(aps_account_number, ""),
             ECMPAdditionalField(aps_account_security_code, "")
             .....
)

Индивидуальный дизайн

Дизайн платёжной формы SDK для Android можно менять:
  • использовать светлую или тёмную тему,

    Рис.: Светлая тема платёжной формы



    Рис.: Тёмная тема платёжной формы



  • настраивать оформление отдельных элементов.

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

SDK для Android позволяет использовать две темы платёжной формы: светлую (по умолчанию) и тёмную. Для смены темы необходимо установить:

Рис.: Java

ECMPTheme theme = ECMPTheme.getDarkTheme();
startActivityForResult(ECMPActivity.buildIntent(this,
               paymentInfo,
               theme),
               PAY_ACTIVITY_REQUEST);

Рис.: Kotlin

val theme = ECMPTheme.getDarkTheme()
startActivityForResult(
   ECMPActivity.buildIntent(
               this,
               paymentInfo,
               theme
    ),
    PAY_ACTIVITY_REQUEST
 )

Настройка оформления отдельных элементов

Также можно настраивать цветовое оформление отдельных элементов. Например:

Рис.: Java

theme.fullScreenBackgroundColor = Color.GREEN;
theme.showShadow = false;

Рис.: Kotlin

theme.fullScreenBackgroundColor = Color.GREEN
theme.showShadow = false
Оформление платёжной формы можно настраивать с помощью следующих параметров:
  • overlayColor — цвет затемнения открытой области платёжной формы,
  • statusBarColor — цвет строки состояния,
  • modalBackgroundColor — цвет фона модального окна,
  • fullScreenBackgroundColor — цвет фона платёжной формы в полноэкранном режиме,
  • headingTextColor — цвет текста заголовка,
  • menuTextColor — цвет текста кнопок в заголовке модального окна,
  • fieldTextColor — цвет текста дополнительных полей, названий платёжных методов, данных на странице с информацией о результате проведения платежа,
  • fieldPlaceholderTextColor — цвет заполнителей полей,
  • fieldImageTintColor — цвет иконок в полях ввода при оплате новой картой и в поле CVV,
  • fieldBackgroundColor — цвет кнопок платёжных систем и поля CVV,
  • fieldUnderlineSelectedColor — цвет нижней линии полей ввода при выборе поля в фокус,
  • fieldUnderlineDefaultColor — цвет нижней линии полей ввода по умолчанию,
  • fieldUnderlineErrorColor — цвет нижней линии полей ввода при неуспешной проверке заполненного поля,
  • navigationBarItemsColor — цвет кнопок панели навигации,
  • navigationBarColor — цвет панели навигации,
  • primaryTintColor — основной цвет кнопок и иконок платёжной формы,
  • secondaryTintColor — вспомогательный цвет платёжной формы,
  • actionButtonDisableBackgroundColor — цвет заблокированной кнопки,
  • actionButtonDisableTextColor — цвет текста на заблокированной кнопке,
  • actionButtonTextColor — цвет текста на активной кнопке,
  • supportiveTextColor — цвет вспомогательного текста,
  • secureKeyboardTextColor — цвет цифр экранной клавиатуры,
  • showShadow — включение тени кнопок платежных методов и сохранённых карт на странице выбора платёжных методов,
  • showLightLogo — включение светлых логотипов при использовании тёмной темы.