Table of Contents
Overview
There are two possible tipping options in the Payment Device SDK - End of Day, and On Device.
To enable tipping functionality, you will first need to make a TMS Request to our support team to enable this for you (specifying you would like On Device, End of Day, or both for your Terminal ID).
End of Day
End of Day tipping typically works under the assumption that you will receive the tipping amount after the transaction has taken place (such as on a receipt at a restaurant). This is enabled in two steps. Firstly, when initiating an authorization you will need to set the AmountType parameter to the value of AmountTypeEstimate. This informs our platform that the amount in the authorization is subject to change pending tipping.
Secondly, and more importantly, you will need to initiate a confirmation, updating the final amount and setting the CloseTransaction parameter value to True which will then flag the transaction to be settled for the updated amount. Note: If the CloseTransaction parameter is not included and set to True the transaction will stay in a partially committed state, and will not go for settlement.
An example of confirmation parameters to be sent to the confirmTransaction() method:
Android:
// The user reference of the original transaction authorized requestParameters.add(ParameterKeys.UserReference, "User Reference"); // The agreed amount in the original transaction requestParameters.add(ParameterKeys.Amount, "1000"); // The amount to be added for End of Day tipping (can be null if none) requestParameters.add(ParameterKeys.TipAmount, null); /* End of Day tipping will require every transaction to be confirmed with the Close Transaction flag set to true, if this is not done, the transaction will not be settled. */ requestParameters.add(ParameterKeys.CloseTransaction,ParameterValues.TRUE); // Initiate the confirmation ChipDnaMobile.getInstance().confirmTransaction(requestParameters);
iOS:
// The user reference of the original transaction authorized [request setValue:_UserReference forKey:CCParamUserReference]; // The agreed amount in the original transaction [request setValue:_Amount forKey:CCParamAmount]; // The amount to be added for End of Day tipping (can be nil if none) [request setValue:nil forKey:CCParamTipAmount]; /* End of Day tipping will require every transaction to be confirmed with the Close Transaction flag set to true, if this is not done, the transaction will not be settled. */ [request setValue:CCValueTrue forKey:CCParamCloseTransaction]; // Initiate the confirmation [[ChipDnaMobile sharedInstance] confirmTransaction:request];
On Device
On-device tipping will prompt the customer for tipping options on the PED, asking for confirmation on whether the customer would like to tip, and then prompt for the amount to tip for. To enable this, add the flag when initiating an authorization, as shown below:
Android:
// The amount to charge requestParameters.add(ParameterKeys.Amount, currentlySelectedAmount); // The amount to charge is not an estimate, so will need to be set as actual requestParameters.add(ParameterKeys.AmountType, ParameterValues.AmountTypeActual); // Currency for the transaction set elsewhere requestParameters.add(ParameterKeys.Currency, CURRENCY); // Set a user reference requestParameters.add(ParameterKeys.UserReference, "User Reference"; /* Enable the type of tipping you would like to use On Device Tipping */ requestParameters.add(ParameterKeys.TippingType, ParameterValues.OnDeviceTipping);
/* End of Day Tipping */
requestParameters.add(ParameterKeys.TippingType, ParameterValues.EndOfDayTipping);
/* Both On Device Tipping and End of Day Tipping */
requestParameters.add(ParameterKeys.TippingType, ParameterValues.BothTipping); // Transaction is a sale, set as such requestParameters.add(ParameterKeys.TransactionType, ParameterValues.Sale); // Payment method is card, set as such requestParameters.add(ParameterKeys.PaymentMethod, ParameterValues.Card); // Initiate the transaction ChipDnaMobile.getInstance().startTransaction(requestParameters);
iOS:
// The amount to charge [request setValue:_Amount forKey:CCParamAmount]; // The amount to charge is not an estimate, so will need to be set as actual [request setValue:CCValueAmountTypeEstimate forKey:CCParamAmountType]; // Currency for the transaction set elsewhere [request setValue:_CURRENCY forKey:CCParamCurrency]; // Set a user reference [request setValue:_UserReference forKey:CCParamUserReference];
/* Enable the type of tipping you would like to use
On Device Tipping */
[request setValue:CCValueOnDeviceTipping forKey:CCParamTippingType];
/* End of Day Tipping */
[request setValue:CCValueEndOfDayTipping forKey:CCParamTippingType];
/* Both On Device Tipping and End of Day Tipping */
[request setValue:CCValueBothTipping forKey:CCParamTippingType]; // Transaction is a sale, set as such [request setValue:CCValueSale forKey:CCParamTransactionType]; // Payment method is card, set as such [request setValue:CCValueCard forKey:CCParamPaymentMethod]; // Initiate the transaction [[ChipDnaMobile sharedInstance] startTransaction:request];