Tip Integration

This page contains the requirements for integrating the tip enhancements. Please implement below items in your application.

To enable tipping directly on the device, you can add this functionality to your application by following the development steps outlined below.

1. Flow

A tip selection flow has been added after selecting the credit card in the sales flow.

2. Bank App Protocol

On the protocol side, the tipAmount fields have been added to the sales request and sales response. Details regarding these fields are provided below.

2.1 Sale

The tipAmount field has been added to the intent sent to the Bank App in the sales request. It is included in the example below.

Intent IntentCard = new Intent();
		IntentCard.setPackage(tag);
		IntentCard.setAction(getResources().getString(R.string.Sale_Action)); //Sale_Action="Sale_Action"
        Bundle bundle_card = new Bundle();
	      bundle_card.putInt("Amount",amount);
        bundle_card.putInt("CardReadType",cardReadType);
        bundle_card.putString("CardData",cardData); 
        bundle_card.putString("UUID",uuid); 
	      bundle_card.putInt("allowedCardType",allowedCardType);
	      bundle_card.putInt("isGIBTerminal",isGIBTerminal);
	      bundle.putBoolean("isDovizPOS", isDovizPOS)
	      bundle.putInt("currenyRate", currencyRate)
	      bundle.putInt("currenyUnit", currencyUnit)
        bundle.putString("currencyCode", currencyCode)
        bundle.putInt("currenyAmount", currencyAmount)
        bundle.putLong("tipAmount") //Added
        IntentCard.setType("text/plain");
        IntentCard.putExtras(bundle_card);
        startActivityForResult(IntentCard, getResources().getInteger(R.integer.Sale_Request_Code)); //Sale_Request_Code=1

NOTE: The amount field includes the tip amount and is transmitted as a single value. Additionally, the tip amount is transmitted in the tipAmount field.

NOTE: In transactions where a tip entry is provided, if the selected bank does not support tip processing, the amount field will still include the tip amount and be sent to the bank as the total of base amount + tip amount. However, the VAT (KDV) rate applied on the receipt will be calculated and displayed based on the product’s predefined VAT rate, with the tip amount treated as part of the product amount rather than a separate component.

2.1.1 Sale Response

The tipAmount field has been added to the sales response we use. It is included in the example.

   void onSaleResponseRetrieved(Integer price, ResponseCode code, Boolean hasSlip, SlipType slipType, String cardNo, String ownerName) {
        Intent resultIntent = new Intent();
        Bundle bundle = new Bundle();
        bundle.putInt("ResponseCode", code.ordinal());
        bundle.putInt("PaymentStatus",0);
        bundle.putInt("Amount",price);
        bundle.putInt("Amount2", price);        
        bundle.putInt("BatchNo",0);
        bundle.putInt("TxnNo",0);
        bundle.putInt("InstallmentCount", installmentCount);
        bundle.putBoolean("IsSlip", hasSlip);
        bundle.putInt("SlipType", slipType.value);
        bundle.putString("RefundInfo", refund_info); 
        bundle.putString("CardNo", cardNo);
        bundle.putString("TID", terminal_id);
        bundle.putString("MID", merchant_id);	    
        bundle.putString("RefNo", ref_no);
        bundle.putString("AuthNo", auth_no);
        bundle.putLong("tipAmount",tipAmount);
   
       
        if (slipType == SlipType.CARDHOLDER_SLIP || slipType == SlipType.BOTH_SLIPS) {
            bundle.putString("customerSlipData", PrintHelper.getFormattedText(getSampleReceipt(cardNo, ownerName), SlipType.CARDHOLDER_SLIP));
        }
        if (slipType == SlipType.MERCHANT_SLIP || slipType == SlipType.BOTH_SLIPS) {
            bundle.putString("merchantSlipData", PrintHelper.getFormattedText(getSampleReceipt(cardNo, ownerName), SlipType.MERCHANT_SLIP));
        }
        resultIntent.putExtras(bundle);
        setResult(Activity.RESULT_OK,resultIntent);
        finish();
    }

NOTE: The amount value shall include both the transaction amount and the tip amount. Additionally, the tip amount shall be transmitted separately via the tipAmount field.

2.2 Parameter

Add TipAllowed into Allowed Operations as Parameter Action Response Data if Tip Allowed supported.

Allowed Operations

Allowed Operations will be added with the "AllowedOperations" tag. The allowed transaction types will be provided as a JSON object. It will indicate whether tip entry is allowed on the terminal. "TipAllowed" will be set to “1” if tip entry is supported, and “0” if it is not supported.

Allowed Operations Bundle Example

AllowedOperations={"TipAllowed":1,"QrAllowed":1,"KeyInAllowed":0, "DovizPOSAllowed":1, "CarPayAllowed":1}

3 Example Videos

3.1 Sale Flow

There are two examples in the attached video. In the first example, a 10% tip is selected for a 500 TL sale. In the second example, a 20 TL tip is entered for a 250 TL sale.

tipSale.mov

3MB

Open