.. meta::
   :description: SBC mPOS SDK для Android и Java: интеграция транзакций с присутствием карты в приложении с поддержкой Bluetooth-ридеров, EMV-чипов и бесконтактных платежей.

.. _mpos_sdk_for_android_and_java:

mPOS SDK для Android и Java
#############################


.. role:: ex

.. role:: code

Введение
------------
SBC mPOS SDK — это программно-аппаратный комплекс мобильных платежей, позволяющий быстро и легко начать предоставлять сервис мобильных платежей. Использование доступного мобильного POS-терминала (mPOS) позволяет Присоединяющейся Стороне расширить свой бизнес за счёт очных безналичных платежей.

.. uml::
    :align: center

    @startuml
    left to right direction
    rectangle "Mobile Device" {
    (mPOS SDK)  #ffe6cc;line:black;line.dotted
    (Mobile App)
    }
    (SBC) -- (mPOS SDK)
    (SBC) - (Acquirer Bank)
    (mPOS SDK) -- (Mobile App)
    (mPOS device) - (mPOS SDK)
    @enduml

PayneteasyReader SDK обеспечивает быструю интеграцию с :ref:`mPOS<mpos_integration>` терминалами в мобильных приложениях.

Возможности

- Работает как на Android, так и на Java
- Транзакции MSR, контактные EMV, бесконтактные EMV
- Транзакции с подтверждением подписью или PIN-кодом
- Удалённая загрузка ключей
- Удалённое обновление прошивки
- Удалённая настройка mPOS
- Сертифицирован OpenWay. Первое мобильное POS-решение Chip&PIN в России — |openwaygroup_link|
- Пользовательские сообщения на LCD-экране для всех стадий (только Miura)
- Единый API для всех ридеров
- Реализован :ref:`API сервера SBC<mpos_api>`
- Множество типов транзакций: sale, preauthorization, capture, cancel, reversal, частичный reversal и др.

.. |openwaygroup_link| raw:: html

   <a href="https://www.openwaygroup.com/news_card.jsp?dcion=908&rgn=1&lng=1" rel="nofollow noopener noreferrer">news_card.jsp</a>

.. note::
    | Требования: SDK поддерживает целевое развёртывание на Android от 2.2 и Oracle JVM (протестировано на 1.8)

Поддерживаемые терминалы
--------------------

.. list-table::
  :widths: 30, 50, 50
  :header-rows: 1
  :class: longtable

  * - Производитель
    - Модель
    - Подключение
  * - Miura
    - M006, M007, M010
    - Поддержка транзакций MSR, Contact, Contactless. С PIN-кодом и без. Удалённая загрузка ключей, удалённая настройка, удалённое обновление MPI и ОС
  * - Spire
    - SPm2
    - Bluetooth
  * - Verifone
    - Vx820
    - Ethernet, USB, RS232
  * - PAX
    - SP30
    - Ethernet, USB, RS232


.. note::
    | Все терминалы поддерживают удалённую настройку и обновление прошивки.

.. warning::
    | Поддержка прекращена с 1 января 2015 г.:
    | GD Seed: интеграция с официальным SDK.
    | GD Seed: собственный SDK. С оптимизацией памяти и производительности.
    | ID Tech Unimag II: интеграция с официальным SDK.
    | ID Tech Unimag II: собственный SDK. Оптимизация памяти и производительности. Расширяет список поддерживаемых моделей телефонов.
    | Bluebamboo P25.

.. warning::
    | На стадии оценки:
    | Datecs DRD50, DRD10
    | Datecs MPED400, Bluepad 50
    | Wizar POS
    | BBPOS

Интеграционная среда
------------

The SDK includes a maven repository - http://paynet-qa.clubber.me/reader/maven/
For Miura Shuttle model: Use TEST on emulators for events.

Настройка maven
===========

`Android Maven-репозиторий можно найти здесь <https://github.com/payneteasy/reader-example>`_. Добавьте репозиторий в pom.xml:

::

  <repository>
    id>reader-repo</id>
    <name>reader repo</name>
    <url>http://paynet-qa.clubber.me/reader/maven</url>
  </repository>`

Настройка gradle
============

`Android Gradle-репозиторий можно найти здесь <https://github.com/payneteasy/reader-example-gradle>`_. Добавьте следующее в секцию repositories:

::

  repositories {
 ...
    maven { url "https://jitpack.io" }
    maven { url "http://paynet-qa.clubber.me/reader/maven" }
 ...
  }

- Добавьте следующее в зависимости:

::

  dependencies {
  ...
    def readerVersion = // check the latest version :ref:`here<https://github.com/payneteasy/reader-example/wiki/Changelog>`
    compile 'com.payneteasy.android.reader:api:' + readerVersion
    compile ('com.payneteasy.android.reader:lib:' + readerVersion)

    compile 'com.payneteasy.android.reader.readers:readers-common-bluetooth:' + readerVersion
    compile ('com.payneteasy.android.reader.readers:readers-miura:' + readerVersion) {
        exclude group:'junit', module:'junit'
    }
  ...
  }

Подробнее см. полный `пример Gradle, доступный здесь <https://github.com/payneteasy/reader-example-gradle>`_.

Для Bluetooth-ридеров (Android)
===============================

Добавьте следующее в AndroidManifest.xml:

::

 <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

Для USB-терминалов (Android)
===========================

- Добавьте новый файл res/xml/device_filter.xml:

::

  <?xml version="1.0" encoding="utf-8"?>
  <resources>

    <!-- 0x1234 / 0x0101  PAX / S80 -->
    <usb-device vendor-id="4660" product-id="257" class="255" subclass="0" protocol="0"/>

    <!-- 0x11CA / 0x0219  VeriFone Inc / Trident USB Device 1.1 / bInterfaceClass = 10 CDC Data -->
    <usb-device vendor-id="4554" product-id="537" class="10" subclass="0" protocol="0"/>

  </resources>

- Добавьте любой элемент activity в AndroidManifest.xml:

::

  <intent-filter>
        <action android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" />
    </intent-filter>
    <meta-data  android:name="android.hardware.usb.action.USB_DEVICE_ATTACHED" android:resource="@xml/device_filter" />`

- Добавьте в activity:

::

 public class MainActivity extends Activity {

    private final UsbPermissionResolver usbPermissionResolver = new UsbPermissionResolver();

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        usbPermissionResolver.checkPermission(getIntent(), this);
    }

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        usbPermissionResolver.checkPermission(intent, this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        usbPermissionResolver.unregister(this);
    }

    ...

    }

.. note::
    | Подробнее см. `этот коммит <https://github.com/payneteasy/reader-example-gradle/commit/2aa02c47f38cef4f3a673e98fc5d5ecb98720656>`_.

Для Miura (Java)
================

См. пример app-2 — как запустить и собрать приложение для ридеров Miura для работы на JVM.

app-3-webstart показывает, как запустить приложение из браузера через Java WebStart:

- `mPOS SDK в Linux <https://www.youtube.com/watch?v=rLSx3SrkMqA>`_
- `mPOS SDK + Java Web Start в Mac OS X <https://www.youtube.com/watch?v=OgdUfHqBvmI>`_
- `mPOS SDK в Windows <https://www.youtube.com/watch?v=I6PPO-j9KSk>`_

Пример кода
===========

Реализуйте интерфейс IReaderPresenter:

::

  @Override
    public ProcessingContinuation onCard(BankCard bankCard) {

        setStatus("onCard: %s", bankCard);

        return ProcessingContinuation.Builder
                .startSaleOnline()
                .processingBaseUrl  ( Config.SERVER_BASE_URL)
                .merchantLogin      ( Config.MERCHANT_LOGIN )
                .merchantControlKey ( Config.MERCHANT_KEY   )
                .merchantEndPointId ( Config.END_POINT_ID   )
                .orderDescription   ( "test description"    )
                .orderInvoiceNumber ( "invoice-"+System.currentTimeMillis())
                .orderMerchantData  ( "custom merchant data for a internal use")
                .customerPhone      ( "+7 499 918-64-41"    )
                .customerEmail      ( "info@payneteasy.com" )
                .customerCountry    ( "RUS"                 )
                .listener(new IProcessingStageListener() {
                    @Override
                    public void onStageChanged(ProcessingStageEvent aEvent) {
                        setStatus("processing: %s", aEvent);
                    }
                })
                .build();

    }

    @Override
    public void onReaderSerialNumber(String aKsn) {
        setStatus("onReaderSerialNumber: %s", aKsn);
    }

    @Override
    public void cardReaderStateChanged(CardReaderEvent cardReaderEvent) {
        setStatus("cardReaderStateChanged: %s", cardReaderEvent);
    }

    @Override
    public void onCardError(CardError cardError) {
        setStatus("onCardError: %s", cardError);
    }

    @Override
    public void onReaderNotSupported(CardReaderProblem aProblem) {
        setStatus("onReaderNotSupported: %s", aProblem);
    }

    @Override
    public void onAudioData(short[] shorts, int i) {
        // for visualization
    }

    @Override
    public ConfigurationContinuation onConfiguration() {
        return new ConfigurationContinuation.Builder()
                .configDir              ( new File(activity.getFilesDir(), "miura-config"))
                .configurationBaseUrl   ( Config.SERVER_CONFIG_URL  )
                .merchantLogin          ( Config.MERCHANT_LOGIN     )
                .merchantControlKey     ( Config.MERCHANT_KEY       )
                .merchantEndPointId     ( Config.END_POINT_ID       )
                .build();
    }

.. note::
    | Заполните Config.MERCHANT_LOGIN, Config.MERCHANT_KEY, Config.END_POINT_ID собственными значениями.

Запускает Reader Manager:

::

  CardReaderInfo cardReader = CardReaderInfo.TEST;
  BigDecimal amount = new BigDecimal(1);
  String currency = "RUB";

  SimpleCardReaderPresenter presenter = new SimpleCardReaderPresenter(this, statusView);
  cardReaderManager = CardReaderFactory.findManager(this, cardReader, presenter, amount, currency, null);`

Deal with картаReaderМенеджер:

- ICardReaderManager.startSaleSession() запускает сессию продажи
- ICardReaderManager.stopSession() останавливает сессию и освобождает ресурсы


Полезные ссылки
-------------

- `Приложение 4 rxtx qbang <https://github.com/payneteasy/reader-example/tree/master/app-4-rxtx-qbang>`_
- `Документация Java API <http://paynet-qa.clubber.me/reader/apidocs/>`_
- Дополнительные примеры предоставляются по запросу.
- `Другие релизы можно найти здесь <https://github.com/payneteasy/reader-example/wiki/Changelog>`_.