Configure Tipping in Commerce Engine

Description: Learn how to set up and manage on-device tipping in Commerce Engine, including device-configured, POS-controlled, and POS-managed tipping models.

---

Commerce Engine supports on-device tipping, allowing you to capture tips as part of the payment flow. Tipping can be configured to prompt automatically on every transaction, or controlled by the POS application for more flexibility.

Choosing a Tipping Model

Commerce Engine supports three tipping models. Start with who owns the shopper interaction — if the tip prompt should always live on the payment device, use a Commerce Engine-owned flow. If the POS owns the prompt or collects the tip elsewhere, use the POS-managed model.

Model	Shopper Interaction	Commerce Engine Role
Device-Configured	On the payment device	Commerce Engine owns the prompt and tip options
POS-Controlled	On the payment device	Commerce Engine renders the prompt; the POS controls how it behaves
POS-Managed	On the POS or another customer-facing surface	Commerce Engine passes through the tip amount provided by the POS

Device-Configured

The simplest on-device tipping flow. When tipping is enabled on the device, the customer is automatically prompted to add a tip during the payment flow, typically before the card is presented. This approach requires no additional integration logic from the POS.

Capabilities:

• Enable or disable tip prompting
• Configure three preset tip percentages
• Set a default pre-selected option

Note: Use this model when the tip prompt should behave the same way on every transaction.

POS-Controlled

The most flexible on-device tipping flow. The shopper still sees the tip screen on the payment device, but the POS decides when it appears and what options are shown on each transaction.

Capabilities:

• Choose percentages, fixed amounts, or free-entry tipping
• Set three suggested tip values
• Choose which suggestion is pre-selected
• Set the prompt heading shown on the device
• Show a tip-based message when the tip is calculated from a specific amount

Note: Use this model when the tipping experience varies by workflow, ticket type, or POS context.

POS-Managed

Commerce Engine does not own the tip prompt in this model. The tip amount is included directly in the payment request by the POS. Commerce Engine does not display any tip options on the device.

Capabilities:

• Tip prompt lives entirely in the POS experience
• Useful when the POS runs on a customer-facing device
• Useful when you have a separate Customer-facing Display

Note: This is not a Commerce Engine tipping flow. The POS owns the prompt, the choices, and the shopper interaction.

Receipt Handling

For all three tipping models, use the tip amount and updated total returned in the payment response when printing receipts. The original pre-tip amount from the request should also be shown on the receipt for transparency.