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, and 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 let config = toroconfig( gratuityconfig gratuityconfig(mode standard), // ) 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 let metadata = transactionmetadata( gratuityconfig gratuityconfig( mode configured, percentages \[20, 10, 5], header "select a tip / gratuity " ) ) toro starttransaction( amount 1000, type purchase, currency gbp, metadata 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 standard) supplying amounts or percentages in standard mode will cause starttransaction() to fail with a validation error 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 configured, amounts \[300, 200, 100], // rendered as £3 00, £2 00, £1 00 header "select a tip / gratuity " ) percentage based gratuityconfig( mode configured, percentages \[20, 10, 5], // rendered as 20%, 10%, 5% header "select a tip / gratuity " ) mixing amounts and percentages in the same config will cause starttransaction() to fail with a validation error customising prompt text two text fields control what is shown on device before and during tip selection addgratuityprompt text shown on the initial yes/no screen asking the cardholder whether they want to add a tip (default "add gratuity?" , max 30 characters) header title shown at the top of the tip selection menu (default "select tip" , max 30 characters) gratuityconfig( mode configured, percentages \[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 in // 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 let metadata = transactionmetadata( gratuityamount 100 // £1 00 ) toro starttransaction( amount 1100, // £11 00 total (£10 00 + £1 00 tip) type purchase, currency gbp, metadata metadata, // ) transactionmetadata gratuityamount and a non none gratuityconfig cannot both be set on the same transaction starttransaction() will fail with a validation error 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