SDK для Android (legacy)

Возможности

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

Состав

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

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

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

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

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

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

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

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

Подключение библиотек через 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
                  );

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

   Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения. К параметрам с информацией о платёжном адресе пользователя относятся код страны в формате ISO 3166-1 alpha-2 (billingCountry), индекс (billingPostal), название города (billingCity) и название улицы (billingAddress).

   Дополнительно могут использоваться следующие объекты и параметры:

   • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
   • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
   • customerID — идентификатор пользователя, уникальный в рамках проекта.
   • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
   • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
   • token — токен карты.
   • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды платёжных методов.
   • 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

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

   Вместе с тем, рекомендуется передавать эти и ряд других параметров (с информацией о платёжном адресе пользователя) для проведения оплат с использованием карт всех платёжных систем, поскольку по данным платёжной системы Visa полноценное использование таких параметров может существенно (вплоть до 6 %) повышать проходимость платежей и кардинально (вплоть до 65 %) снижать число операций, признаваемых мошенническими после их выполнения. К параметрам с информацией о платёжном адресе пользователя относятся код страны в формате ISO 3166-1 alpha-2 (billingCountry), индекс (billingPostal), название города (billingCity) и название улицы (billingAddress).

   Дополнительно могут использоваться следующие объекты и параметры:

   • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
   • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платёжной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
   • customerID — идентификатор пользователя, уникальный в рамках проекта.
   • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
   • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
   • token — токен карты.
   • forcePaymentMethod — идентификатор платежного метода, который откроется в платёжной форме по умолчанию без возможности выбора пользователем другого платёжного метода. Список идентификаторов приведен в разделе Коды платёжных методов.
   • 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)

Обзор

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

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());
        }
    };
}

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)
        }
    }
}

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

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

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

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

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

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

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

paymentInfo.setToken(token);

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

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

"account": {
            "number": "541333****0019",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2024"
        },

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

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize);

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Tokenize)

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

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

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

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

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

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

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

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

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

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

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify);

paymentInfo.setAction(ECMPPaymentInfo.ActionType.Verify)

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

SDK для Android поддерживает проведение оплат с использованием альтернативных платёжных методов: Google Pay, Skrill Wallet, DOKU Wallet, Banks of Malaysia, Banks of Thailand, Alipay, Neteller, а также оплат с использованием интернет-банкинга в странах Европы. В большинстве случаев пользователь перенаправляется к сервису платёжного метода для завершения оплаты. Описание каждого из этих методов представлено в отдельной статье, а далее также приведено описание особенностей работы с методом Google Pay.

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

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

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