Gratuity

tipping modes the sdk supports three gratuity modes, configured via gratuityconfig mode mode description gratuitymode none no tipping prompt is shown this is the default gratuitymode standard the sdk shows a built in tipping menu with 10%, 15%, and 20% options no additional configuration required gratuitymode configured the sdk builds a tipping menu from the fixed amounts or percentages you supply in standard and configured modes, the sdk handles the full on device flow automatically, including the initial "add gratuity?" yes/no prompt, the selection menu, a built in "other amount" option for free form tip entry global configuration set gratuityconfig in toroconfig to apply the same tipping behaviour to every transaction val config = toroconfig( gratuityconfig = gratuityconfig(mode = gratuitymode standard), // )toroconfig config = new toroconfig( // new gratuityconfig(gratuitymode default), // ); per transaction configuration pass a gratuityconfig in transactionmetadata to override the global config for a specific transaction this is the recommended approach when tipping behaviour varies per transaction for example, when switching between amounts and percentages based on business logic val metadata = transactionmetadata( gratuityconfig = gratuityconfig( mode = gratuitymode configured, percentages = listof(20, 10, 5), header = "select a tip / gratuity " ) ) toro starttransaction( amount = 1000, type = transactiontype purchase, currencycode = currencycode gbp, metadata = metadata, // )gratuityconfig gratuityconfig = new gratuityconfig( gratuitymode configured, collections emptylist(), arrays aslist(20, 10, 5), "add gratuity?", "select a tip / gratuity " ); transactionmetadata metadata = new transactionmetadata( null, 0, null, gratuityconfig, collections emptymap() ); toro starttransaction( 1000, transactiontype purchase, currencycode gbp, metadata, // ); standard mode gratuitymode standard presents a built in tipping menu with 10%, 15%, and 20% options no amounts or percentages need to be supplied gratuityconfig(mode = gratuitymode standard)new gratuityconfig(gratuitymode default) supplying amounts or percentages in standard mode will throw an illegalargumentexception use configured mode instead configured mode gratuitymode configured lets you define exactly which amounts or percentages to offer supply either amounts (in pence) or percentages not both a maximum of 3 options may be provided the sdk automatically appends an "other amount" option for free form entry fixed amounts gratuityconfig( mode = gratuitymode configured, amounts = listof(300, 200, 100), // rendered as £3 00, £2 00, £1 00 header = "select a tip / gratuity " )new gratuityconfig( gratuitymode configured, arrays aslist(300, 200, 100), // rendered as £3 00, £2 00, £1 00 collections emptylist(), "add gratuity?", "select a tip / gratuity " ) percentage based gratuityconfig( mode = gratuitymode configured, percentages = listof(20, 10, 5), // rendered as 20%, 10%, 5% header = "select a tip / gratuity " )new gratuityconfig( gratuitymode configured, collections emptylist(), arrays aslist(20, 10, 5), // rendered as 20%, 10%, 5% "add gratuity?", "select a tip / gratuity " ) mixing amounts and percentages in the same config will throw an illegalargumentexception customising prompt text two text fields control what is shown on device before and during the tip selection addgratuityprompt text shown on the initial yes/no screen asking the cardholder whether they want to add a tip (default "add gratuity?" ) header title shown at the top of the tip selection menu (default "add gratuity?" , max 30 characters) gratuityconfig( mode = gratuitymode configured, percentages = listof(20, 10, 5), addgratuityprompt = "add a tip?", header = "select a tip / gratuity " ) responding to the customer's selection when the customer confirms a tip, the ongratuityconfirmed callback is triggered ongratuityconfirmed = { gratuityamount, gratuitypercentage > // gratuityamount tip in the smallest currency unit (e g pence) // gratuitypercentage whole number percentage (e g 15), or 0 for a fixed amount or free form tip } if the customer declines the tip, ongratuityconfirmed is still called with gratuityamount = 0 custom pre transaction flow if you prefer to collect the tip before calling starttransaction() , for example in your own application ui, pass it directly via transactionmetadata gratuityamount in this case leave gratuityconfig unset (or set mode to none ) and include the tip in the total amount val metadata = transactionmetadata( gratuityamount = 100 // £1 00 ) toro starttransaction( amount = 1100, // £11 00 total (£10 00 + £1 00 tip) type = transactiontype purchase, currencycode = currencycode gbp, metadata = metadata, // )transactionmetadata metadata = new transactionmetadata( null, 100, // £1 00 null, null, collections emptymap() ); toro starttransaction( 1100, // £11 00 total (£10 00 + £1 00 tip) transactiontype purchase, currencycode gbp, metadata, // ); transactionmetadata gratuityamount and a non none gratuityconfig cannot both be set on the same transaction this will throw an illegalargumentexception the amount parameter in starttransaction() must be the total transaction amount, including any gratuity the ongratuityconfirmed callback is not triggered when using the custom pre transaction flow