General information
SDK Assist.Mobile makes it possible to simplify the development of a mobile app of an online store for making the bank card payments with mobile devices using IPS Assist.
The users of SDK Assist.Mobile are the developers of the mobile app of the online store.
This document contains sufficient information on installing, configuring and using the Assist.Mobile SDK to use it.
System requirements
To work with Assist.Mobile, you need to use Android SDK version 26 or higher (Android 8.0 Oreo).
Description of SDK Assist.Mobile
The Assist.Mobile SDK is a mobilePay-release-X.X.X.aar file. To access the functionality of the library, you must use the class:
ru.assisttech.sdk.AssistSDK
This class contains the following method:
AssistPayEngine AssistSDK.getPayEngine(Activity activity)
The method returns an instance of a class that implements payment functions for individuals.
After receiving the AssistPayEngine object, you need to initialize it to make a payment. To do this, you need to set the address of the server through which payment will be made by calling the method:
assistPayEngine.setServerURL(String url).
To control and receive the result of the work of AssistPayEngine, the PayEngineListener interface is used, which is installed by the method:
void assistPayEngine.setEngineListener(PayEngineListener listener).
To start the payment process, use the following method:
assistPayEngine.payWeb(Activity caller, AssistPaymentData data, boolean useCamera),
where
caller – Activity, from which the payment process is launched;
data - object, parameters and data required for making a payment;
useCamera - a flag indicating to use the mobile device's camera to read the customer's bank card number or enter the number manually.
Additionally, you can check the result of the payment using the method:
void assistPayEngine.getOrderResult(Activity caller, long id).
You can interrupt the payment process using the following method:
void assistPayEngine.stopPayment(Activity caller).
The ru.assisttech.sdk.AssistPaymentData class, which allows you to set payment parameters, contains the following methods:
- void setMerchantId(String value) – the method allows you to set the identifier of the store, specifying the identifier of the store is mandatory;
- void setOrderNumber(String value) – the method allows you to set the order number, specifying the order number is mandatory;
- void setOrderAmount(String value) - the method allows you to set the order amount (the string value of the amount in kopecks is used), setting the order amount is mandatory;
- void setOrderCurrency(Currency value) - the method allows you to set the currency of the order;
- void setOrderComment(String value) - the method allows you to set a comment - a description of the payment;
- void setEmail(String value) - the method allows you to set the payer's e-mail address;
- void setAddress(String value) - the method allows you to set the payer's postal address;
- void setHomePhone(String value) - the method allows you to set the payer's home phone number;
- void setWorkPhone(String value) - the method allows you to set the payer's work phone number;
- void setMobilePhone(String value) - the method allows you to set the mobile phone number of the payer;
- void setFax(String value) - the method allows you to set the fax number of the payer;
- void setLastname(String value) - the method allows you to set the last name of the payer;
- void setFirstname(String value) - the method allows to set the first name of the payer;
- void setMiddlename(String value) - the method allows you to set the middle name of the payer;
- void setCountry(String value) - the method allows you to set the country of the payer;
- void setState(String value) - the method allows you to set the state (region);
- void setCity(String value) - the method allows you to set the city;
- void setZip(String value) - the method allows you to set the postal code;
- void setSignature(String value) - method allows you to set the parameter signature.
The string is generated from order parameters with semicolon as delimiter. The following parameters are included in the string: Merchant _ ID;OrderNumber;OrderAmount;OrderCurrency. Then the MD5 hash prepared from this string. Hash is signed by private RSA key of the merchant. Key length - 1024. Received byte sequence is a signature of the merchant. Signature is transferred as an additional parameter encoded as a string in BASE64 format.
Storage of payment results
The payments made are stored in SQLite DB, which is accessed through the AssistTransactionStorage interface and the AssistTransactionFilter and AssistTransactionsLoader classes.
The AssistTransactionStorage class is for accessing a single transaction by ID, while the AssistTransactionsLoader is used to get a list of transactions without blocking the main application thread.
The AssistTransactionFilter class is used to filter the list of transactions received from the AssistTransactionStorage.
You can get an instance of the AssistTransactionStorage class using the method:
AssistTransactionStorage assistPayEngine.transactionStorage().
An instance of the AssistTransactionsLoader class must be created in the onCreateLoader(int id, Bundle args) method of the class that implements the LoaderManager.LoaderCallbacks<> interface.
Google Pay support
To work with Google Pay, it is recommended that you first read the documentation on the developer's website https://developers.google.com/pay.
At the moment, work with the Google wallet is presented in the SANDBOX mode. Therefore, to determine the possibility of making a test payment, you need to contact the Assist support service support@assist.ru.
Samsung Pay support
To use Samsung Pay in their app, a merchant needs to sign up with Samsung and register their app, then get the Samsung Pay SDK http://www.samsung.com/ru/apps/mobile/samsungpay/.
Next, you should create a certificate request, issue a merchant certificate in Samsung and transfer it to Assist via support@assist.ru to connect the Samsung Pay service.
In your app, you need to follow Samsung's instructions to initiate a payment with Samsung Pay. To complete the Samsung Pay payment, you need to transfer the data received from the Samsung Pay SDK to Assist using the AssistPayEngine.payToken() function.
The order of integration of the online store mobile app with SDK Assist.Mobile
To integrate the mobile app of the online store with SDK Assist.Mobile, you must perform the following steps:
- Copy the mobilePay-release-X.X.X.aar file to the /libs directory of the app module.
Add to module's build.gradle.
repositories { flatDir { dirs 'libs' } } dependencies { compile 'io.card:android-sdk:5.0.0' compile(name: 'mobilePay-release-X.X.X', ext: 'aar') }- Make following changes in AndroidManifect.xml:
3.1. First you need to make sure that the minimum SDK version is 26 or higher. There should be an tag like this inside the <manifest> tag:
<uses-sdk android:minSdkVersion="26"/>
3.2. The following permissions must also be present inside the <manifest> tag:
<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. Add an activity to the <application> tag:
<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. Before releasing the app, you need to add to the proguard configuration file:
```
-keep class io.card.**
-keepclassmembers class io.card.** {
*;
}
-keep class ru.assisttech.sdk.**
-keepclassmembers class ru.assisttech.sdk.** {
*;
}
```
An example of payment implementing using the Assist.Mobile SDK
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);
// Getting a payment component from the library
engine= AssistSDK.getPayEngine(this);
// Setting the server address
engine.setServerURL("server url");
// Setting the listener of the result
engine.setEngineListener(this);
findViewById(R.id.btPay).setOnClickListener(new View.OnClickListener(){
@Override
public void onClick(View v) {
// Setting payment options
AssistPaymentData data = new AssistPaymentData();
// Merchant ID in IPS Assist
data.setMerchantId("12345");
// Order number
data.setOrderNumber("OrderNo");
// Amount
data.setOrderAmount("100"); // 100 RUB
// Currency
data.setOrderCurrency(AssistPaymentData.Currency.RUB);
// Comment
data.setOrderComment("Test payment");
// Payer's e-mail
data.setEmail("customer@mail.com");
// Payer's postal address
data.setAddress("Москва, Ленинградское ш. 39");
// Home phone
data.setHomePhone("567-99-29");
// Work phone
data.setWorkPhone("555-00-00");
// Mobile phone
data.setMobilePhone("+79067410863");
// Fax
data.setFax("");
// Lastname
data.setLastname("Романов");
// First name
data.setFirstname("Пётр");
// Middle name
data.setMiddlename("Алексеевич");
// Payer country
data.setCountry("Russia");
// Region (state)
data.setState("Moscow");
// City
data.setCity("Moscow");
// Postal code
data.setZip("100290");
// Language
data.setLanguage(AssistPaymentData.Lang.RU);
// Payment parameters signature calculation...
String signature = "stub_signature";
// Signature setting
data.setSignature(signature);
// Starting the payment process
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("Error: " + info);
}
@Override
public void onNetworkError(Activity activity, String s) {
tvPaymentResult.setText("Network error: " + s);
}
}
The SDK and the sample app are available for download at the following link:
https://github.com/assist-group/assist-mcommerce-sdk-android