Общие сведения

SDK Assist.Mobile позволяет упростить разработку мобильного приложения интернет-магазина для проведения через АПК Assist платежей банковской картой с мобильных устройств.

Пользователями SDK Assist.Mobile являются разработчики мобильного приложения интернет-магазина.

Настоящий документ содержит сведения по установке, настройке и использованию SDK Assist.Mobile, достаточные для его применения.

Системные требования

Для работы с Assist.Mobile необходимо использовать Android SDK версии не ниже 26 (Android 8.0 Oreo).

Описание SDK Assist.Mobile

SDK Assist.Mobile представляет собой файл mobilePay-release-X.X.X.aar. Для доступа к функционалу библиотеки необходимо использовать класс:

ru.assisttech.sdk.AssistSDK

Этот класс содержит следующий метод:

AssistPayEngine AssistSDK.getPayEngine(Activity activity)

Метод возвращает экземпляр класса, реализующего функции оплаты для частных лиц.

После получения объекта AssistPayEngine для проведения оплаты необходимо его инициализировать. Для этого требуется установить адрес сервера, через который будет проводиться оплата вызовом метода:

assistPayEngine.setServerURL(String url).

Для контроля и получения результата работы AssistPayEngine используется интерфейс PayEngineListener устанавливаемый методом:

void assistPayEngine.setEngineListener(PayEngineListener listener).

Для запуска процесса оплаты используется метод:

assistPayEngine.payWeb(Activity caller, AssistPaymentData data, boolean useCamera),

где

caller – Activity, из которой осуществляется запуск процесса оплаты;

data — объект, содержащий параметры и данные, необходимые для проведения платежа;

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

Дополнительно проверить результат платежа можно с помощью метода:

void assistPayEngine.getOrderResult(Activity caller, long id).

Прервать процесс оплаты можно с помощью метода:

void assistPayEngine.stopPayment(Activity caller).

Класс ru.assisttech.sdk.AssistPaymentData, позволяющий устанавливать параметры оплаты, содержит следующие методы:

  • void setMerchantId(String value) – метод позволяет установить идентификатор торговой точки, задание идентификатора торговой точки обязательно;
  • void setOrderNumber(String value) – метод позволяет установить номер заказа, задание номера заказа обязательно;
  • void setOrderAmount(String value) - метод позволяет установить сумму заказа (используется строковое значение суммы в копейках), задание суммы заказа обязательно;
  • void setOrderCurrency(Currency value) - метод позволяет установить валюту заказа;
  • void setOrderComment(String value) - метод позволяет установить комментарий - описание платежа;
  • void setEmail(String value) - метод позволяет установить адрес электронной почты плательщика;
  • void setAddress(String value) - метод позволяет установить почтовый адрес плательщика;
  • void setHomePhone(String value) - метод позволяет установить домашний телефон плательщика;
  • void setWorkPhone(String value) - метод позволяет установить рабочий телефон плательщика;
  • void setMobilePhone(String value) - метод позволяет установить мобильный телефон плательщика;
  • void setFax(String value) – метод позволяет установить номер факса плательщика;
  • void setLastname(String value) - метод позволяет установить фамилию плательщика;
  • void setFirstname(String value) - метод позволяет установить имя плательщика;
  • void setMiddlename(String value) - метод позволяет установить отчество плательщика;
  • void setCountry(String value) - метод позволяет установить страну плательщика;
  • void setState(String value) - метод позволяет установить область (регион);
  • void setCity(String value) – метод позволяет установить город;
  • void setZip(String value) - метод позволяет установить почтовый индекс;
  • void setSignature(String value) – метод позволяет установить подпись параметров.

Формируется строка, сшитая из следующих параметров заказа: MerchantId;OrderNumber;OrderAmount;OrderCurrency, разделенных точкой с запятой. На базе этой строки алгоритмом MD5 формируется дайджест. Дайджест подписывается закрытым RSA ключом мерчанта. Длина ключа - 1024. Полученная байтовая последовательность является подписью магазина. Подпись передается в запросе как дополнительный параметр, закодированный в виде строки BASE64.

Хранение результатов оплаты

Проведенные оплаты сохраняются в SQLite DB, доступ к которой осуществляется через интерфейс AssistTransactionStorage и классы AssistTransactionFilter и AssistTransactionsLoader.

Класс AssistTransactionStorage предназначен для доступа к единичной транзакции по ID, в то время как AssistTransactionsLoader используется для получения списка транзакций без блокирования основного потока приложения.

Класс AssistTransactionFilter используется для фильтрации списка транзакций, получаемых от AssistTransactionStorage.

Получить экземпляр класса AssistTransactionStorage можно с помощью метода:

AssistTransactionStorage assistPayEngine.transactionStorage().

Экземпляр класса AssistTransactionsLoader необходимо создавать в методе onCreateLoader(int id, Bundle args) класса, реализующего интерфейс LoaderManager.LoaderCallbacks<>.

Поддержка Google Pay

Для работы с Google Pay рекомендуется предварительно ознакомиться с документацией на сайте разработчика https://developers.google.com/pay.

На данный момент работа с кошельком Google представлена в режиме SANDBOX. Поэтому для определения возможности проведения тестового платежа требуется связаться со службой поддержки Assist support@assist.ru.

Поддержка Samsung Pay

Для использования Samsung Pay в своем приложении предприятию необходимо зарегистрироваться в Samsung и зарегистрировать свое приложение, а затем получить Samsung Pay SDK http://www.samsung.com/ru/apps/mobile/samsungpay/.

Далее следует создать запрос на сертификат, выпустить сертификат магазина в Samsung и передать его в Assist через support@assist.ru для подключения услуги Samsung Pay.

В своем приложении необходимо следовать инструкции Samsung для инициации платежа через Samsung Pay. Для завершения оплаты Samsung Pay нужно передать данные, полученные из Samsung Pay SDK в Assist с помощью функции AssistPayEngine.payToken().

Порядок интеграции мобильного приложения интернет-магазина с SDK Assist.Mobile

Для интеграции мобильного приложения интернет-магазина с SDK Assist.Mobile необходимо выполнить следующие действия: 

  1. Скопировать файл mobilePay-release-X.X.X.aar в каталог /libs модуля приложения.
  2. Добавить в build.gradle модуля:


              repositories {
                  flatDir {
                      dirs 'libs'
                  }
               }
 
              dependencies {
                  compile 'io.card:android-sdk:5.0.0'
                  compile(name: 'mobilePay-release-X.X.X', ext: 'aar')
              }

3. Сделать следующие изменения в AndroidManifect.xml:

3.1.        Сначала необходимо убедиться, что минимальная версия SDK 26 или выше. Должен быть примерно такой тег внутри тега <manifest>:

        <uses-sdk android:minSdkVersion="26"/>

3.2.             Также внутри тега <manifest> должны присутствовать следующие разрешения:

             <uses-permission android:name="android.permission.INTERNET" />
             <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />        
             <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
             <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
             <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
 
             <uses-permission android:name="android.permission.CAMERA" />
             <uses-permission android:name="android.permission.VIBRATE" />

             <uses-feature android:name="android.hardware.camera" android:required="false" />
             <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
             <uses-feature android:name="android.hardware.camera.flash" android:required="false" />    

3.3.        В тег <application> следует добавить activity:

             <activity
                 android:name="ru.assisttech.sdk.processor.WebViewActivity"
                 android:configChanges="keyboardHidden|orientation|screenSize">
             </activity>
             <activity
                 android:name="io.card.payment.CardIOActivity"
                 android:configChanges="keyboardHidden|orientation" />
             <activity android:name="io.card.payment.DataEntryActivity" />

3.4.             Перед выпуском приложения в релиз нужно добавить в файл конфигурации proguard:

                 ```
                -keep class io.card.**
                -keepclassmembers class io.card.** {
                 *;
                }    
                -keep class ru.assisttech.sdk.**
                -keepclassmembers class ru.assisttech.sdk.** {
                 *;
                }
                ```

Пример реализации оплаты с помощью SDK Assist.Mobile

package ru.assisttech.example;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.widget.TextView;
import ru.assisttech.sdk.AssistSDK;
import ru.assisttech.sdk.AssistPaymentData;
import ru.assisttech.sdk.engine.AssistPayEngine;
import ru.assisttech.sdk.engine.PayEngineListener;
import ru.assisttech.sdk.storage.AssistTransaction;
public class
MainActivity extends
Activity implements
PayEngineListener { 
    private TextView tvPaymentResult;
    private AssistPayEngine
engine;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        tvPaymentResult = (TextView) findViewById(R.id.textView);
        // Получение платежного компонента из библиотеки
        engine= AssistSDK.getPayEngine(this);
        // Установка адреса сервера
        engine.setServerURL("server url");
        // Установка получателя результата
        engine.setEngineListener(this);

        findViewById(R.id.btPay).setOnClickListener(new View.OnClickListener(){

            @Override
            public void onClick(View v) {
                // Установка параметров платежа
                AssistPaymentData data = new AssistPaymentData();
                // ID мерчанта в АПК Ассист
                data.setMerchantId("12345");
                // Номер заказа
                data.setOrderNumber("OrderNo");
                // Сумма
                data.setOrderAmount("100"); // 100 руб
                // Валюта
                data.setOrderCurrency(AssistPaymentData.Currency.RUB);
                // Комментарий
                data.setOrderComment("Тестовый платеж");
                // e-mail покупателя
                data.setEmail("customer@mail.com");
                // Почтовый адрес покупателя
                data.setAddress("Москва, Ленинградское ш. 39");
                // Домашний телефон
                data.setHomePhone("567-99-29");
                // Рабочий телефон
                data.setWorkPhone("555-00-00");
                // Мобильный телефон
                data.setMobilePhone("+79067410863");
                // Факс
                data.setFax("");
                // Фамилия
                data.setLastname("Романов");
                // Имя
                data.setFirstname("Пётр");
                // Отчество
                data.setMiddlename("Алексеевич");
                // Страна покупателя
                data.setCountry("Russia");
                // Область (штат)
                data.setState("Moscow");
                // город
                data.setCity("Moscow");
                // Почтовый индекс
                data.setZip("100290");
                // Язык
                data.setLanguage(AssistPaymentData.Lang.RU);
                // Вычисление подписи параметров платежа ...
                String signature = "stub_signature";
                // Установка подписи
                data.setSignature(signature);
                // Запуск процесса оплаты
                engine.payWeb(MainActivity.this, data, false);
            }
        });
    }
    /**
     * PayEngineListener callbacks
     */
    @Override
    public void onFinished(Activity activity, AssistTransaction assistTransaction) {
        if (!this.equals(activity)) {
            activity.finish();
        }
        tvPaymentResult.setText(assistTransaction.getResult().getOrderState().toText());
    }

    @Override
    public void onCanceled(Activity activity, AssistTransaction assistTransaction) {
        if (!this.equals(activity)) {
            activity.finish();
        }
        tvPaymentResult.setText(assistTransaction.getResult().getOrderState().toText());

    }

    @Override
    public void onFailure(Activity activity, String info) {
        tvPaymentResult.setText("Ошибка: " + info);
    }

    @Override
    public void onNetworkError(Activity activity, String s) {
        tvPaymentResult.setText("Сетевая ошибка: " + s);
    }
 }

SDK и пример приложения доступны для скачивания по следующей ссылке:

https://github.com/assist-group/assist-mcommerce-sdk-android

Наверх