App to app

Android

This section describes the steps required to perform an “app to app” call on Android applications. The technical development process consists of 3 different steps:

Step 1: Create an intent to call mPOS

Step 2: Define the object class MessageToSend

Step 3: Get a response from mPOS

Step 1: Create an intent to call mPOS

Communication with the mPOS application is done by using Android intents. This means that the call to the mPOS 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 mPOS can be found in the following code sample:

private Intent createPendingIntent(String reference, String value){
 Intent launchIntent = new Intent();

 //Package of Smartpos that will be called
launch.Intente.setClassName(“pt.sibs.android.mpos.sibsPagamentosQly”,”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();
 value? value.replaceAll(“[^\\d.]”, ””);
 messageToSend.setAmount(value);
 messageToSend.setReference(reference);
 Gson gson = new GsonBuilder().create();
 String message = gson.toJson(messageToSend,MessageToSend.class);

 // create json to a Base64byte[] bytes;
 bytes = message.getBytes(StandardCharsets.UTF_8);
 String base64msg = Base64.encodeToString(bytes, Base64.DEFAULT);

  // create a bundle and intent to call mpos and send data over
 Bundle data = new Bundle();
 data.putString(PACKAGE_ID, BuildConfig.APPLICATION_ID);
 data.putBoolean(REQUEST RESPONSE, sw.isChecked());
 data.putBoolean(BYPASS_INSERT_VALUE, bypassSw.isChecked());
 data.putBoolean(EDITABLE_REFERENCE, editReferenceSw.isChecked());
 data.putBoolean(CALL_IN_APP_FECHO, fechoSw.isChecked());
 data.putString(BASE64REFERENCE, base64msg);
 data.putInt(REQUEST_KEY, activityRequestCode);
 launchIntent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);
 launch.Intent.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 mPOS 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 values for both the “reference” and “amount” fields, which are required for the mPOS transaction.

After creating the object and filling in the values of both fields, the object is converted to json, using the Gson lib , and then encode the json string into Base64.

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 mPOS;
• Boolean values indicating whether the app requires a response from the mPOS; allows to edit the amount and reference; whether it will execute a Closure instead of a Purchase;
• 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.

The development and production packages will be made available to developers once the integration journey initiates.

Step 2: Define the object class MessageToSend

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;
• reference: this field informs the reference associated to the operation. It is of the String type, 25- character length (maximum). May contain alphanumeric values.

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

class MessageToSend {
 @SerializedName("reference")
 private String reference;
 @SerializedName("ammount")
 private String ammount;

 void setReference(String reference) {
 this.reference = reference;
 }
 void setAmmount(String amount) {
 this.ammount = amount;
 }
}

Step 3: Get a response from mPOS

After the execution of the operation, a response can be received from the mPOS, if the flag corresponding to the key “REQUEST_RESPONSE” marks the value true.

The following example illustrates how to read the response if it comes via on ActivityResult or on NewIntent:

@Override
protected void onNewIntent(Intent intent) {
 String status = "";
 String errorCode = "";
 String date = "";
 String reference = "";
 String amount = "";
 String mbwayDataJson = "";
 MBWayCallInAppData mbwayCallInAppData = new MBWayCallInAppData();

 // get response from mposif(intent != null && intent.getExtras() != null) {
 
 if(intent.getExtras().containsKey(CALLIN ERROR KEY))
 errorCode = intent.getExtras().getString(CALLIN_ERROR_KEY);
 
 if(intent.getExtras().containsKey(CALLIN STATUS KEY))
 status = intent.getExtras().getString(CALLIN_STATUS_KEY);

 if(intent.getExtras().containsKey(CALLIN DATE KEY))
 date = intent.getExtras().getString(CALLIN_DATE_KEY);

 if(intent.getExtras().containsKey(CALLIN AMOUNT KEY))
 amount = intent.getExtras().getString(CALLIN_AMOUNT_KEY);

 if(intent.getExtras().containsKey(CALLIN REF))
 reference = intent.getExtras().getString(CALLIN_REF);

 Toast.makeText(getApplicationContext(), "STATUS2: "+status+"\nError: "+errorCode+"\nAmount: "+ amount + "\nDate: "+date+"\nReference: "+reference, Toast.LENGTH LONG).show());
 }
 super.onNewIntent(intent);
}@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
 if(requestCode == activityRequestCode) {
 String status = "";
 String errorCode = "";
 String date = "";
 String reference = "";
 String amount = "";

 if(data != null && data.getExtras() != null) {
 if (data.getExtras().containsKey(CALLIN ERROR KEY))
 errorCode = data.getExtras().getString(CALLIN ERROR KEY);
 
 if (data.getExtras().containsKey(CALLIN_STATUS_KEY))
 status = data.getExtras().getString(CALLIN STATUS KEY);

 if (data.getExtras().containsKey(CALLIN_DATE_KEY))
 date = data.getExtras().getString(CALLIN DATE KEY);

 if (data.getExtras().containsKey(CALLIN_AMOUNT_KEY))
 amount = data.getExtras().getString(CALLIN DATE KEY);

 if (data.getExtras().containsKey(CALLIN_REF))
 reference = data.getExtras().getString(CALLIN REF);

 Toast.makeText(getApplicationContext(), "STATUS2: "+status+"\nError: "+errorcode+"\nAmount: "+ amount +"\nDate: "+date+"\nReference: "+reference, Toast.LENGTH LONG.show());
 }
 }
}

In either case, an Intent is received containing a Bundle filled by the mPOS with the response data.

After validating that the Intent exists and contains the Bundle, the values of each Key will be obtained, if present.

The response returns 6 values, detailed on the following tables:

MB WAY client data*

The json has the following structure:

{
  "fiscalIdentificationNumber": "123456789 ",
   "email": “email_de_teste@sibs.com”
}

Below you can find a table with the Used Keys and correspondent definition.

iOS

This section describes the steps required to perform a “app to app” call on iOS applications. The technical development itself requires 3 steps:

Step 1: Configure the application

Step 2: Create the data model to transfer to mPOS

Step 3: Get a response from mPOS

Step 1: Configure the application

To receive responses from the mPOS, the client application must configure a URL Type in the project’s Info.plist. The name (scheme) must be defined in the URL Schemes field – this is the name by which the mPOS app will make the “app to app” call to obtain the answer with the result of the operation performed in the mPOS.

In the following example, the “app-to-app” scheme must be replaced by the client application scheme:

Step 2: Create the data model to transfer to mPOS

The call to the mPOS by an iOS app is made through a data model (in json format in base64) based on the following parameters:

{
 "reference" : “ABCDEFG”, 
 "amount" : “3284”, 
 "lockAmountValue" : 1, 
 "performAutomaticClose" : 1, 
 "urlScheme": @“callinapp://" 
}

Below, we provide you with a table with the details of the date model briefly described:

The following code sample represents a “app to app” call made to mPOS by an iOS app:

(void) openAppWithScheme:(NSString*)scheme { 
 NSNumberFormatter *numberFormatter = [[NSNumberFormatter alloc] init]; 
 numberFormatter.numberStyle = NSNumberFormatterDecimalStyle; 
 
 int amount = [numberFormatter numberFromString:@“32,84”].floatValue * 100; 
 NSDictionary *paramsDic = @{@"reference" : @"ABCDEFG", 
 @"amount" : [NSString stringWithFormat:@"%i", amount], 
 @"lockAmountValue" : [NSNumber numberWithBool:YES], 
 @"performAutomaticClose" : [NSNumber numberWithBool:YES], 
 @"urlScheme": @"callinapp://" 
 }; 
 
 NSData *jsonData = [NSJSONSerialization dataWithJSONObject:paramsDic options:0error:nil]; 
 NSString *jsonParms = [jsonData base64EncodedStringWithOptions:0]; 

 NSString *url = [NSString stringWithFormat:@"%@://%@", scheme, jsonParms]; 

  [[UIApplication sharedApplication] openURL:[NSURL URLWithString:url] 
options:@{ UIApplicationOpenURLOptionUniversalLinksOnly: @NO} completionHandler:^(BOOL success) { 
  NSLog(@"URL: %@", url); 
 NSLog(@"Success: %@", success ? @"YES": @"NO"); 
 } 
 ]; 
}

Step 3: Get a response from mPOS

The mPOS application, upon receiving a “app to app” call processes the requested operation returning the response to the client application with the result (success or error) of the operation. This response is returned to the client application using the following data model defined in JSON in base 64

{
 @"callInError" : “”, 
 @"callInStatus" : “APPR”, 
 @"callInAmount" : “3284”, 
 @"callInDate": “2020-05-04T11:42:38.001+01:00”, 
 @"callInRef": “ABCDEFG”
 @"callInMBWayCustomerData": “{"fiscalIdentificationNumber": "123456789 ", "email": “email_de_teste@sibs.com”}”
}

Here is a brief description with the meaning of the different fields:

CallInMBWayCustomerData *

The json has the following structure:

{
  "fiscalIdentificationNumber": "123456789 ",
  "email": “email_de_teste@sibs.com”
}

Below we provide you an example of how to process an mPOS response in the AppDelegate file of the iOS project:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options: (NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options { 
 [self parsePaymentResponse:url]; 
 return YES; 
} 

-(void)parsePaymentResponse:(NSURL*_Nullable)url { 
  if(!url) 
 return; 

  NSString *base64Encoded = [url.absoluteString stringByReplacingOccurrencesOfString:@"callinapp://" withString:@""]; 
 if(!base64Encoded) 
 return; 
 
 NSData *nsdataFromBase64String = [[NSData alloc] initWithBase64EncodedString:base64Encoded options:0]; 
 if(!nsdataFromBase64String) 
 return; 

 NSError *error; 
 NSDictionary *dicParams = [NSJSONSerialization JSONObjectWithData:nsdataFromBase64String options:0 error:&error]; 
 if(!dicParams || error) 
 return; 
 
 NSLog(@"%@", dicParams); 
 NSString *result = [NSString stringWithFormat:@"%@", dicParams]; 
 UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Resposta" message:result preferredStyle:UIAlertControllerStyleAlert]; 
[alert addAction:[UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:nil]]; 
[self.window.rootViewController presentViewController:alert animated:YES completion:nil]; 

}