Our app-to-app integration enables a seamless connection between your merchant app and our SoftPOS app, providing customers with a quick and secure way to complete their payments. Check out the details below to get started with the integration for Android.

Android

Check out the steps required to perform an “app-to-app” call on Android applications. The development process involves three steps:

Step 1: Create an intent to call SoftPOS

Step 2: Get a response from SoftPOS

Step 1: Create an intent to call SoftPOS

Communication with the SoftPOS application is done by using Android intents. This means that the call to the SoftPOS by an Android app is made through an Intent which contains a bundle with the required information for the transaction.

The data sent to the SoftPOS can be found in the following code sample:

private Intent createPendingIntent(String amount, int timer) {
        Intent launchIntent = new Intent();

        //Package of Smartpos that will be called
        launchIntent.setClassName(“pt.sibs.android.mpos.stargatePaytelQLY”,”pt.sibs.android.mpos.activities.MainActivity”);

        TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
        stackBuilder.addNextIntent(launchIntent);

        // create a json with value and reference
        MessageToSend messageToSend = new MessageToSend();
        amount = amount.replaceAll("[^\\d.]", "");
        messageToSend.setAmount(amount);    

        Gson gson = new GsonBuilder().create();
        String message = gson.toJson(messageToSend,MessageToSend.class);

        // convert json to a Base64
        byte[] bytes;
        bytes = message.getBytes(StandardCharsets.UTF_8);
        String base64msg = ByteHelper.toBase64(bytes);

        // create a bundle and intent to call mpos and send data over
        Bundle data = new Bundle();
        data.putString("PACKAGE_ID", BuildConfig.APPLICATION_ID);
        data.putString("BASE64REFERENCE", base64msg);

        data.putBoolean("RETURN_VALUE_BOOLEAN", true);
        data.putBoolean("lockAmountValue", true);
        data.putBoolean("AUTO_CLOSE_RECEIPT_SCREEN", true);
        data.putInt("AUTO_CLOSE_RECEIPT_TIMER", 5000);

        launchIntent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
        launchIntent.putExtra("DATA_MPOS", data);

        return launchIntent;
}

The example illustrates a method that in the end returns an Intent with the necessary information. The Intent is created first, then the setClassName method is used to configure the SoftPOS Package and the Activity that will be invoked, in this case MainActivity. The name of the Activity to be used in the “app to app” call is: pt.sibs.android.mpos.activities.MainActivity.

After configuring the Intent, an object of a custom type called MessageToSend is created.

This object is used to hold the amount of the transaction, which is required for the SoftPOS transaction.

After creating the object and setting the amount, the object is converted to json, using the Gson lib , and then the json string is encoded into Base64.

In this object, the following fields must be populated:

• amount this field contains the operation amount and is represented in cents.
  Example: for a €10 purchase, the amount must be populated with ‘1000’. This field type is String;

Here is a code sample of the Class Message to send:

class MessageToSend {
    @SerializedName("amount")
    private String amount;
}

After filling the object, we can create the Bundle to be passed along with the Intent. The Bundle must contain the following elements:

• A String with the Application ID of the app which is calling the SoftPOS;
• Boolean values indicating whether the app requires a response from the SoftPOS; allows to edit the amount;
• A String with the Base64-encoded JSON data;
• An Integer value used in the StartActivity that will use the Intent created by this method.

When the Bundle has been created, the FLAG_ACTIVITY_SINGLE_TOP flag is configured in the Intent. This flag is a configuration setting for the intent that specifies how the Activity should behave when it’s started. The keys used in the Bundle will be described further down in this guide. The development and production packages will be made available to developers once the integration journey initiates.

Create bundle with keys:

User keys	Key definition
DATA_MPOS	The key of the Bundle object used to send data to the SoftPOS app. Type Bundle. Mandatory.
PACKAGE_ID	The application ID of the app which is calling the SoftPOS app. Type String. Mandatory.
BASE64REFERENCE	Value (in base 64) of the json created from the object MessageToSend with the amount. Type String. Mandatory.
RETURN_VALUE_BOOLEAN	Flag indicating whether the app that is invoking the SoftPOS requires a response. Type boolean.
lockAmountValue	Flag indicating whether the app that is invoking the SoftPOS allows amount to be changed. Type boolean.
AUTO_CLOSE_RECEIPT_SCREEN	Flag indicating whether the SoftPOS app should close after the operation. Type boolean.
AUTO_CLOSE_RECEIPT_TIMER	Time to close the app after the success/declined screen, in milliseconds. Type int.

Step 2: Get a response from SoftPOS

After the execution of the operation, a response can be received from the SoftPOS app, if the flag corresponding to the key “RETURN_VALUE_BOOLEAN” is set to true.

The following example illustrates how to read the response if it comes via onNewIntent:

@Override
protected void onNewIntent(Intent intent) {
    String status;
    String errorCode;
    String date;
    String amount;
    int merchantId;
    String transactionId;

    // get response from softpos
    if (intent != null && intent.getExtras() != null) {
        if (intent.getExtras().containsKey("CALL_IN_ERROR"))
            errorCode = intent.getExtras().getString("CALL_IN_ERROR");
        if (intent.getExtras().containsKey("CALL_IN_STATUS"))
            status = intent.getExtras().getString("CALL_IN_STATUS");
        if (intent.getExtras().containsKey("CALL_IN_DATE"))
            date = intent.getExtras().getString("CALL_IN_DATE");
        if (intent.getExtras().containsKey("CALL_IN_AMOUNT"))
            amount = intent.getExtras().getString("CALL_IN_AMOUNT");
        if (intent.getExtras().containsKey("CALLIN_MERCHANT_ID"))
            merchantId = intent.getExtras().getInt("CALLIN_MERCHANT_ID");
        if (intent.getExtras().containsKey("CALLIN_TRANSACTION_ID"))
            transactionId = intent.getExtras().getString("CALLIN_TRANSACTION_ID");

        String result = "STATUS1: " + status + "\nError: " + errorCode + "\nAmount: " + amount + "\nDate: " + date + "\nMerchant ID: " + merchantId + "\nTransaction ID: " + transactionId;
            Log.e("CALL_IN_APP_RESULT", result);
            Toast.makeText(getApplicationContext(), result, Toast.LENGTH_LONG).show();
        } else {
            Toast.makeText(getApplicationContext(), "STATUS2: NO DATA", Toast.LENGTH_LONG).show();
        }
    super.onNewIntent(intent);
}

Either getting the response via onActivityResult or onNewIntent, an Intent is received containing a Bundle filled by the SoftPOS app with the response data.

After validating that the Intent exists and contains the Bundle, the values for each key can be obtained, if present.

The response Bundle may contain up to 6 keys, detailed on the following table:

Key name	Description	Value type
“CALL_IN_ERROR”	Response code (if any) obtained by the SoftPOS app while performing the operation. May be present in a success response.	String
“CALL_IN_STATUS”	Informs the status of the operation performed by the SoftPOS app, which can be: DeviceError Success Declined CommError Usercancelled UserTimeOut Missing Credentials	String
“CALL_IN_DATE”	Informs the date when the operation was performed.	String
“CALL_IN_AMOUNT”	The value used in the operation performed by SoftPOS, can be used to compare with the value sent in the bundle which invoked the SoftPOS app	String
“CALLIN_MERCHANT_ID”	The id of the merchant in the SoftPOS system.	int
“CALLIN_TRANSACTION_ID”	The id of the transaction in the SoftPOS system.	String