The G1P Mobile SDK is an easy to use library that handles communication with the GlobalOne payment gateway. The SDK wraps a REST interface to the GlobalOne gateway but also implements the client side security, making it even easier to connect.

Bellow are the plugins that has already been integrated into the GlobalOne payment gateway, which allows a very simple interface for doing transactions.

The SDK has 2 main components:

The Sample app shows how to implement G1P Mobile SDK in your own app.

Minimum Android version supported by the SDK is 4.4.

Installation is as easy as adding the G1P Mobile SDK to your project. The steps for Android are as follows:

Step 1 - Copy the core-sdk.jar to the application folder and add it as a dependency.

Step 2 - Go to the AndroidManifest.xml and set these permissions.

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Step 3 - Copy payconfig.xml into your project's res/values directory.

The payconfig.xml contains URL's used to access the server.

Please make sure to add the file into your project.

Test mode should be used for development, which will use gatewayTestUrl defined in payconfig.xml. To enable test mode.

terminal.setMode(CoreMode.TEST);

To switch back to LIVE mode.

 terminal.setMode(CoreMode.LIVE);

DEV mode is used to point to gatewayDevUrl defined in payconfig.xml file. Dev host usually contains unreleased features. To switch to DEV mode.

 terminal.setMode(CoreMode.DEV);

The application needs to implement the Core API Listener to interact with the SDK. On Android this makes the most sense in the MainActivity as follows:

public class MainActivity implements CoreAPIListener{

onMessage(CoreMessage message);
onSaleResponse(CoreSaleResponse response);
onRefundResponse(CoreRefundResponse response);
onTransactionListResponse(CoreTransactions response);
onLoginUrlRetrieved(String url);
onSignatureRequired(CoreSignature signature);
onError(CoreError error, String message);
onDeviceError(CoreDeviceError error, String message);
onSettingsRetrieved(CoreSettings settings);
onDeviceConnected(DeviceEnum type, HashMap<String, String> deviceInfo);
onDeviceDisconnected(DeviceEnum type);
onSelectApplication(ArrayList<String> applications);
onDeviceConnectionError();
onSelectBTDevice(ArrayList<String>  devices);
onAutoConfigProgressUpdate(String progress);
onReversalRetrieved(CoreResponse reversalResponse);
onSelectSerialPort(ArrayList<String> ports);
onDeviceInfoReturned(HashMap<String, String> deviceInfo);

public void onMessage(CoreMessage message) {
   String message = message.name(); 
   ...
}

public void onSaleResponse(CoreSaleResponse response) {
   String cardType = response.getCardType();
   String name = response.getCardHolderName();  
   ...
}

public void onRefundResponse(CoreRefundResponse response) {
   String cardType = response.getCardType();
   String name = response.getCardHolderName();  
 
   ...
 
}

public void onTransactionListResponse(CoreTransactions response) {
   ArrayList &ltCoreTransactionSummary> list = response.getTransactionSummary();
   for(CoreTransactionSummary tr : list){       
 
   ...
 
   }
 
}

public void onLoginUrlRetrieved(String url) {
      // start browser to log in
      Intent i = new Intent(Intent.ACTION_VIEW);
      i.setData(Uri.parse(url));
      startActivity(i);
}

public void onSignatureRequired() {
   //create canvas to draw a signature and pass the signature object
   signatureCanvas.setSignature(signature);
   signatureCanvas.submitSignature();
}

public void onError(CoreErrorType error, String message) {
   String message = message;
   ...
}

public void onDeviceError(CoreDeviceError error, String message){
   ...
}

public void onSettingsRetrieved(CoreSettings settings) {
   ArrayList<CoreTax> tax = settings.getTaxList();
   ArrayList<CoreTip> tip = settings.getTipList();
   ...
}

public void onDeviceConnected(DeviceEnum type, HashMap
 
               deviceInfo){ String address = deviceInfo.get("bluetoothID"); String supportNFC = deviceInfo.get("isSupportedNfc"); ... }
 

public void onDeviceDisconnected(DeviceEnum type){
   ...
}

public void onSelectApplication(ArrayList<String> applications){
   terminal.submitApplication(0);
}

public void onDeviceConnectionError(){
    ...
}

public void onSelectBTDevice(ArrayList<String>  devices){
    ...
}

public void onAutoConfigProgressUpdate(String progress){
    ...
}

public void onReversalRetrieved(CoreResponse reversalResponse){
    ...
}

public void onSelectSerialPort(ArrayList<String> ports){
    ...
}

public void onDeviceInfoReturned(HashMap<String, String> deviceInfo){
    ...
}

Step 1 - An instance of a Terminal must be created first. Where this is an object that implements the Core API Listener (i.e. this code snippet is done inside the MainActivity)

AndroidTerminal terminal = new AndroidTerminal(this);

Step 2 - Once the AndroidTerminal is created, we need to initialise it.

The arguments are the terminal ID and secret. These are credentials that are required before using the SDK.

terminal.initWithConfiguration(MainActivity.this, TERMINAL_ID, SECRET);

Step 1 - Copy the plugin(s) to your project folder.

Step 2 - Add the libraries as dependencies.

The following permissions need to be added to the AndroidManifest for each plugin.

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

<uses-permission android:name="android.permission.RECORD_AUDIO"/> 
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

Now we can initialise the plugin using our terminal object and the corresponding DeviceEnum value.

terminal.initDevice(DeviceEnum.BBPosDevice, DeviceConnectionType.BLUETOOTH, null);

For devices connecting via bluetooth, onSelectBTDevice method will return list of available devices. We need to choose the device from the list to be able to connect to it.

@Override
public void onSelectBTDevice(ArrayList<String> type) {
}

Make sure to call selectBTDevice (to connect to the device) passing the position of the device from the list.

terminal.selectBTDevice(0);

Create a CoreSale object with the amount.

CoreSale sale = new CoreSale(BigDecimal.valueOf(Double.parseDouble(2.22)));

Make sure onSettingsRetrieved method has been called before processing any transaction.

Call the method processSale from the Terminal object, passing the sale object as the parameter.

terminal.processSale(sale);

Depending on the status of the transaction, the response from the SDK should appear in either:

Response Handling - If all goes well the sale response object is returned in the onSaleResponse sale argument.

For the transaction to be approved, response code which is returned in onSaleReponse must be set A.

Please make sure to check the response code which can be one of the following:

A - Approval (Transaction was approved)

D - Declined (Transaction was declined)

C - Pick Up (Type of decline which means that the card has been marked as lost or stolen by the cardholder)

R - Referral (Type of decline which means that the card has been marked as lost or stolen by the cardholder)

@Override
public void onSaleResponse(final CoreSaleResponse response) {
   String json = response.getAsJsonObject();
   Log.d(TAG, "onSaleResponse ");
}

Error Handling - Or else the onError callback is fired with an error message.

@Override
public void onError(CoreError coreError, String s) {
   Log.d(TAG, "onError");
}

To process keyed transactions

CoreSaleKeyed saleKeyed = new CoreSaleKeyed(BigDecimal.valueOf(12.3));
saleKeyed.setCardHolderName("Test user");
saleKeyed.setCardNumber("4111111111111111");
saleKeyed.setCardCvv("123");
saleKeyed.setCardType("VISA");
saleKeyed.setExpiryDate("1218");
terminal.processSale(saleKeyed);

There are 2 types of transactions that require a signature to be sent with the request.

• All swiped transactions
• Chip and signature transactions

If the signature is collected on the paper receipt please set SignatureCollection field of the CoreSale object to “MANUAL”. This property will make sure that onSignatureRequired is not triggered.

To send a signature you need to collect the details and send them via the CoreSignature object.

The CoreSignature object is created for you and supplied via onSignatureRequired:

@Override
public void onSignatureRequired(final CoreSignature signature) {
   Log.d(TAG, "onSignatureRequired");
   signatureCanvas.setSignature(signature); // View object with signature member variable
}

startTouch(x,y)
moveTouch(x,y)
upTouch(x,y)
clearSignature()
submitSignature()

StartTouch - User has reapplied their finger.

MoveTouch - User has moved their finger.

UpTouch - The user has lifted their finger.

ClearSignature - Clears the signature.

SubmitSignature - Submits the signature.

Use a canvas to call the corresponding signature touch method on the user input.

@Override
public boolean onTouchEvent(MotionEvent event) {
   float x = event.getX();
   float y = event.getY();
 
   switch (event.getAction()) {
      case MotionEvent.ACTION_DOWN:
         signature.startTouch(x, y);
         break;
      case MotionEvent.ACTION_MOVE:
         signature.moveTouch(x, y);
         break;
      case MotionEvent.ACTION_UP:
         signature.upTouch();
         break;
  }
 
  return true;
}

When the signature is completed, submitSignature method should be called to let the SDK know that the user has completed the signature.

terminal.submitSignature(signature);

Authentication token is used for every request that requires user authentication

• Refunds
• Reporting of Transactions
• Updating Terminal Settings

Steps to retrieve authentication token from the server

In order to request the URL, custom scheme needs to be defined in your app, for the browser (used for authentication) to send back the token to your application.

Step 1- Define your scheme in android manifest in your activity tag with single instance launch mode.

<activity  android:launchMode="singleInstance">
 
   ...
 
   <intent-filter>
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:host="com.scheme.example" android:scheme="schemeName" />
   </intent-filter>
</activity>

After this point you will be able to redirect to the app from the browser with the valid token after successful authentication.

Once URL scheme has been defined, use terminal object to request a secured URL which takes your URL as a paramater.

terminal.requestSecuredUrl("schemeName://com.scheme.example");

Make sure the custom Scheme passed as a parameter match the one defined in your manifest.

onLoginUrlRetrieved callback method will be triggered with the generated URL. This URL needs to be opened in the browser to login into the selfcare system.

@Override
public void onLoginUrlRetrieved(final String url) {
    Intent i = new Intent(Intent.ACTION_VIEW);
    i.setData(Uri.parse(url));
    startActivity(i);
}

After successful login, the browser will redirects you back to the application with a token in the URI. You must override onNewIntent method which contains URI with the token. The best practice is to store the token in shared preferences as you don't need to login every time to make authenticated requests to the server.

@Override
protected void onNewIntent(Intent intent) {
   super.onNewIntent(intent);
   setIntent(intent);
 
   if (getIntent() != null) {
      Uri data = getIntent().getData();
 
      if (data != null && data.getQueryParameter("authenticationToken") != null) {
         String token = data.getQueryParameter("authenticationToken");
         storeToken(token); // save token in shared preferences
         terminal.setToken(token);
         getIntent().setDataAndType(null, null);
         String date = data.getQueryParameter("validUntilDate");  //contains date when token expires
      }
   }
}

Tell terminal object about the token.

terminal.setToken(token);

Token is unique and valid for 48 hours as a default, after this time re-login will be required and the new token will be generated for this account.

After this point you will be able to process refund, update terminal settings, list transactions.

Refund

CoreUnreferencedRefund refund = new CoreUnreferencedRefund(BigDecimal.valueOf(12.3);
refund.setCardHolderName("Test user");
refund.setCardNumber("4111111111111111");
refund.setCardCvv("123");
refund.setCardType("VISA");
refund.setExpiryDate("1218");
refund.setReason("reason");
 
terminal.processUnreferencedRefund(refund);

Refund response will be returned in onRefundResponse callback method.

List transactions With Filter

CoreTransactionFilter filter = new CoreTransactionFilter();
filter.setItemsPerPage(25);
filter.setState(CoreTransactionState.ALL);
filter.setStartDate("31-12-2015:12:45:30:123");
filter.setEndDate("30-01-2016:12:45:30:123");
terminal.getTransactions(1, filter);

Without Filter

terminal.getTransactions();

The transactions will be returned in onTransactionListResponse callback method.