What is a Tip?

A tip (also called a gratuity) is extra money a customer voluntarily give on top of the bill to thank someone for good service.

How Does the Tip Functionality Work?

Process Description

Step 1:

The MPOS will initiate a GET_TIP request, the GET_TIP request will be sent to the Ecentric Tipping App.

Step 2:

The Ecentric Tipping App will prompt for a tip amount, and a tip amount will be selected.

Step 3:

The Ecentric Tipping App will return the tip amount to the MPOS.

📘
Note
The MPOS will receive three amounts:

transactionAmount – Total amount for the transaction, the full bill amount.

adjustAmount – The tip amount

outstandingAmount - the original bill amount + tip amount

When initiating a payment request after a tip amount has been requested, the MPOS must pass through the outstandingAmount and populate it in the transactionAmount field.

Request

Sample Bundle

The following is an example of a GET_TIP request bundle that the MPOS Application will request.

"launchType": "GET_TIP"
"transactionAmount": 1000

Parameters

The following table describes the parameters of the GET_TIP request message.

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “GET_TIP” Used for launching the Ecentric Tipping App to perform a tip.	GET_TIP
transactionAmount	LONG	The transaction amount to be charged in cents, this will be the full bill amount excluding tip.	1000

Sample Code

The following code needs to be implemented by the MPOS Application in order to invoke the Ecentric Tip App to initiate a GET_TIP request message.

*See Sample Code GET_TIP Response for the intentLauncher function

private void doGetTip() {
   Intent intent = new Intent();
   intent.setClassName("com.ecentric.ecentricpay", "com.ecentric.ecentricpay.MainActivity");
   Bundle dataBundle = new Bundle();
   dataBundle.putString("launchType", "GET_TIP");
   dataBundle.putLong("transactionAmount", 1000);

   intent.putExtra("ecentricBundle", dataBundle);
   try {
       intentLauncher.launch(intent);
   } catch (Exception e) {
       Log.e(TAG, "Error launching intent: " + e);
   }
}

Response

Sample Bundle

The following is an example of a GET_TIP response bundle that the MPOS Application will receive.

Tip Included

"launchType": "GET_TIP",
"resultCode": "00",
"resultDescription": "SUCCESS",
"transactionAmount": 1000,
"adjustAmount": 150,
"outstandingAmount": 1150,
"buildInfo": "com.ecentric.tippingapp-DEBUG",
"appVersion": "1.0"

No Tip

"launchType": "GET_TIP",
"resultCode": "00",
"resultDescription": "SUCCESS",
"transactionAmount": 1000,
"adjustAmount": 0,
"outstandingAmount": 1000,
"buildInfo": "com.ecentric.tippingapp-DEBUG",
"appVersion": "1.0"

Parameters

The following table describes the parameters of the GET_TIP response message.

PARAMETER	TYPE	DESCRIPTION	EXAMPLE
launchType	STRING	Echo of the launchType used to launch the Ecentric Tipping App.	GET_TIP
resultCode	STRING	Represents the result status of the intent call to the Ecentric Tip App ● 01: SUCCESS ● 04: ERROR	01
resultDescription	STRING	A user readable message describing the outcome of the transaction or operation. This field provides additional context, such as actions performed (e.g. tip added) and relevant amounts.	SUCCESS
transactionAmount	LONG	Approved transaction amount, this will be the full bill amount excluding tip. i.e. R100.00	1000
adjustAmount	LONG	Approved tip amount, this will be the tip amount only. i.e. R1.50	150
outstandingAmount	LONG	transactionAmount + adjustAmount	1150
buildInfo	STRING	Details about a specific compiled version of the application.	com.ecentric.tippingapp-DEBUG
appVersion	STRING	The software version currently running on the Ecentric Tipping App.	1.0

Sample Code

The following code needs to be implemented by the MPOS Application to recover the GET_TIP transaction outcome and resume the MPOS App flow accordingly.

When the response is returned the calling app needs to override the onActivityResult() method and can be done as follows:

private final ActivityResultLauncher<Intent> intentLauncher = registerForActivityResult(
       new ActivityResultContracts.StartActivityForResult(),
       result -> {
           if (result.getResultCode() == Activity.RESULT_OK) {
               Intent data = result.getData();
               if (data != null) {
                   Bundle responseBundle = new Bundle(data.getBundleExtra("ecentricApplicationResponse"));
                   String launchType = responseBundle.getString("launchType");

                   Boolean success = false;
                   if (resultCode != null && (resultCode.matches("00") || resultCode.matches("01"))) {
                       success = true;
                   }

                   if (responseBundle.get("errorBundle") != null) {
                       Bundle errorBundle = new Bundle(responseBundle.getBundle("errorBundle"));
                   }
               }
           } else {
               Log.e(TAG, "Received error resultCode: " + result.getResultCode());
           }
       }
);

Error Handling

The following table contains typical errors that might occur and how to handle these errors:

ERROR MESSAGE	SOLUTION
launchType not present	Ensure you provide the launchType “GET_TIP”
transactionAmount not present	Ensure that you are sending through a valid transactionAmount.

Sample Bundle

The following is an example of a GET_TIP ERROR response bundle that the MPOS Application will receive.

"appVersion": "2.1.2",
"buildInfo": "com.ecentric.ecentricpay-DEBUG-Ecentric-[Ecentric_INT]",
"errorBundle": {
  "description": "ERROR",
  "errorType": "OTHER",
  "message": "Error: service com.ecentric.tippingapp not found",
  "reference": ""
},
"resultCode": "04",
"resultDescription": "Error: service com.ecentric.tipping app not found",
"launchType": "GET_TIP"