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.

📘
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.

Tip Request

POST

The following API call types are available for a tip, ensure to make use of the correct endpoint.

API CALL TYPES	ENDPOINT
Asynchronous	/v/1/payment/async
Synchronous	/v/1/payment/sync

Example: Tip

BODY

The following is an example of a GET_TIP request body

{
    "launchType": "GET_TIP",
    "merchantID": "770000000000123",
    "posId": "POS-STORE123-TERM01",
    "serialNumber": "PF5544544664",
    "transactionAmount": 1000
}

String apiUrl = "https://paymentuat.test.thumbzup.com/posbuddy-cloud/v/1/";

JSONObject requestBody = new JSONObject();
requestBody.put("launchType", "GET_TIP");
requestBody.put("merchantID", merchantID);
requestBody.put("posId", posId);
requestBody.put("serialNumber", serialNumber);
requestBody.put("transactionAmount", 1000);

// See Authentication for details of the generateHeaders function
Map<String, String> headers = generateHeaders(secretKey, accessKey, userAgent, serialNumber, posId);
RequestBodyEntity request = Unirest.post(apiUrl + "payment/sync")
        .headers(headers)
        .body(requestBody.toString());

HttpResponse<JsonNode> response = request.asJson();

# See Authentication page for details of the variables
RESPONSE=$(curl --request POST \
  --url "$API_URL/payment/sync" \
  --header "X-pos-id: POS-STORE123-TERM01" \
  --header "X-tu-authorization: protocol:TU1,accesskey:$ACCESS_KEY,signedheaders:User-Agent;X-tu-date;X-tu-random,signature:$SIGNATURE" \
  --header "X-tu-random: $RANDOM_VAL" \
  --header "X-tu-serial: $SERIAL_NUMBER" \
  --header "X-tu-date: $TU_DATE" \
  --header "User-Agent: $USER_AGENT" \
  --header "Content-Type: application/json" \
  --data "{
    \"launchType\": \"GET_TIP\",
    \"merchantID\": \"$MERCHANT_ID\",
    \"posId\": \"POS-STORE123-TERM01\",
    \"serialNumber\": \"$SERIAL_NUMBER\",
    \"transactionAmount\": \"$TRANSACTION_AMOUNT\"
  }" \
 )

Request Body Fields

The following table describes the REQUIRED request body fields of the GET_TIP request message.

FIELD	TYPE	DESCRIPTION	EXAMPLE
REQUIRED
launchType	STRING	Must be “GET_TIP” Used for launching the Ecentric Tipping App to perform a tip.	GET_TIP
merchantID	STRING	The merchant ID assigned to the merchant. The merchant ID will always be the same ID for a specific merchant. To be provided by Ecentric.	910100000000001
posId	STRING	The POS ID is a unique identifier for the originating Point of Sale terminal. In multi-terminal environments, each device requires a distinct alphanumeric identifier (e.g., POS1, POS2, CHECKOUT_A).	POS-STORE123-TERM01
serialNumber	STRING	The serial number of the target payment terminal for this payment request.	PC05P2CG10036
transactionAmount	LONG	The transaction amount to be charged in cents, this will be the full bill amount excluding tip.	1000

Tip Response

Result Codes

RESULTCODE	DESCRIPTION
00	Success
04	Error occurred with the transaction

API Call Types

📘
Note:
Please take note of the tables below around the API Call Type that is being used and the response type that can be expected per API Call Type.

API CALL TYPES	RESPONSE TYPE	DESCRIPTION
Asynchronous	Webhook	If the POS is making use of the Asynchronous REST API call, the POS will receive a JSON BODY response for a tip request, however the JSON BODY response will just be a confirmation that POSBuddy cloud received the request. Once the tip is finalised on the terminal, a webhook callback is sent to the POS to confirm the transaction outcome. The webhook ismandatory when making use of Asynchronous REST API calls. Please refer to the Webhook section to set up webhooks.
Synchronous	JSON BODY	If the POS is making use of the Synchronous REST API call, the POS will receive a JSON BODY response for a tip request. The POS has the option to also receive a webhook response for the tip request, however this is optional.

API CALL TYPES

RESPONSE TYPE

DESCRIPTION

Asynchronous

Webhook

If the POS is making use of the Asynchronous REST API call, the POS will receive a JSON BODY response for a tip request, however the JSON BODY response will just be a confirmation that POSBuddy cloud received the request. Once the tip is finalised on the terminal, a webhook callback is sent to the POS to confirm the transaction outcome. The webhook ismandatory when making use of Asynchronous REST API calls.

Please refer to the Webhook section to set up webhooks.

Synchronous

JSON BODY

If the POS is making use of the Synchronous REST API call, the POS will receive a JSON BODY response for a tip request.

The POS has the option to also receive a webhook response for the tip request, however this is optional.

Example: Tip Included

BODY

The following is an example of a GET_TIP response body the POS Application will receive when a tip has been specified.

{
  "launchType": "GET_TIP",
  "resultCode": "00",
  "resultDescription": "SUCCESS",
  "transactionAmount": 1000,
  "adjustAmount": 150,
  "outstandingAmount": 1150,
  "buildInfo": "com.ecentric.tippingapp-DEBUG",
  "appVersion": "1.0",
  "merchantID": "910100000000001",
  "serialNumber": "PC05P2CG10036",
  "posId": "POS-STORE123-TERM01"
}

Example: No Tip

BODY

The following is an example of a GET_TIP response body the POS Application will receive when a tip has not been specified.

{
  "launchType": "GET_TIP",
  "resultCode": "00",
  "resultDescription": "SUCCESS",
  "transactionAmount": 1000,
  "adjustAmount": 0,
  "outstandingAmount": 1000,
  "buildInfo": "com.ecentric.tippingapp-DEBUG",
  "appVersion": "1.0",
  "merchantID": "910100000000001",
  "serialNumber": "PC05P2CG10036",
  "posId": "POS-STORE123-TERM01"
}

Response Body Fields

The following table describes the response body fields 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 ● 00: SUCCESS ● 04: ERROR	00
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
merchantID	STRING	Echo of the merchantID used in the request	910100000000001
serialNumber	STRING	Echo of the serial number present in the request.	PC05P2CG10036
posId	STRING	Echo of the posId present in the request.	POS-STORE123-TERM01

Error Handling

Example: Errors

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.

BODY

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

{	
  "appVersion": "1.0",
  "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",
  "merchantID": "910100000000001",
  "serialNumber": "PC05P2CG10036",
  "posId": "POS-STORE123-TERM01",
  "launchType": "GET_TIP"
}