Feature Overview
The TreezPay SDK on the SellTreez Front-Facing Display is the first deployment of the plug and play payment widget, purpose built to deliver seamless, self-service payment functionality within the latest version of Treez's customer-facing interface. This integration empowers consumers with direct payment choices while leveraging the robust TreezPay Gateway for secure, efficient transaction management.
Product Taxonomy & Terminology Reference
The feature set lives across multiple services with the following product taxonomy:
TreezPay SDK (Software Development Kit)
A streamlined payment logic layer, leveraging the TreezPay gateway as the engine to handle complex backend processes.
Provides a built-in GUI that manages payment selection, edge cases, and status reconciliation, drawing on insights from the Treez POS payment integration.
Treez FFD (Front Facing Display)
A customer-facing web application designed to empower consumers with self-service checkout, progressively incorporating core POS functionalities for a seamless, autonomous experience.
Treez FFD x SDK
The integration of the TreezPay SDK into the Treez FFD allowing the consumer to fully navigate their own payment experience
Treez FFD x POS
A bi-directional communication layer that ensures seamless interoperability between the POS and FFD, reflecting actions and status updates on each side in real time.
TreezPay Gateway
The engine underneath the TreezPay SDK hood.
Backend service supporting all aspects of payment configuration, routing, validation, and reporting.
TreezPay Portal
A centralized interface for configuring the TreezPay SDK and managing payment settings.
Provides real-time reporting on payments processed through the SDK, streamlining back-office operations.
User Cases
In cannabis retail, budtenders have traditionally controlled the payment process, acting as intermediaries in transactions. This setup can lead to inconsistent promotion of integrated payment options, resulting in lost revenue, as electronic payment transactions often yield higher average order values (AOV) than cash. With payment choices made behind the counter, customers are frequently unaware of all available options, relying on cash by default due to longstanding industry norms.
In non-cannabis retail, however, 84% of U.S. transactions in 2023 were completed using electronic payment methods (ClearlyPayments). This shift toward digital payments aligns with the adoption of customer-facing displays that allow consumers to directly select their preferred payment method, meeting their expectations for convenience, flexibility, and security.
With the introduction of TreezPay on the Treez Front Facing Display, Treez is now positioned to bring this evolution to cannabis retail. Cannabis retailers can now offer customers the autonomy to choose their preferred payment method directly, and align with broader retail trends, enhancing trust and satisfaction while increasing potential revenue through higher AOVs.
Getting Started with TreezPay on the Treez Front Facing Display
Pre-conditions
These are the base conditions which should be met prior to implementing TreezPay on the Treez Front Facing Display in your shop. Please reach out to your dedicated SellTreez or TreezPay customer service reps with questions regarding the pre-conditions.
Store must be underwritten and approved for payment processing through TreezPay
Store should* have payment providers and terminals pre-configured in the TreezPay Portal
Store has compatible customer facing devices on hand
Device compatibility checklist
Web accessible
touch screen
minimum 7'' screen
Necessary Role Permissions
Retail Employee FFD Permissions
SellTreez > Retail > “Pole Display”
Allows retail user to launch / interact with FFD
Admin FFD Permissions
SellTreez > Configurations > “Config Page”
Allows admin to enable the new FFD and TreezPay on the FFD
Minimum Retail Employee Pay Permissions
“TreezPay”
“Create Payment” ← create card payment
“Create Invoice” ← create ACH payment
“Read Entity Configuration” ← read enabled pay methods
“Read Payment Device Location” ← ensure device ready for payment
“Cancel Payment” ← cancel payment in POS
Minimum Admin Pay Permissions:
“TreezPay Platform” > “Organization”
“View” ← View pay provider configs
“Create” ← Create pay provider configs
“Update” ← Update pay provider configs
Configurations & Configuration Business Logic
This section will provide an overview on how to properly configure TreezPay on the Front Facing Display in addition to the business logic one can expect under certain configurations.
Config Flow: Enable TreezPay on Front Facing Display
Enabling the latest version of the customer facing display and payments on the customer facing display can be performed by any privileged user. See pre-conditions > permissions if unable to access this configuration.
Steps
Navigate to Config Page > POS > Front Facing Display
Enable “Connect FFD to POS by Selecting Hardware Location Instead of Cash Drawer”
Enable Treez Pay on Front Facing Display
Enable TreezPay on FFD Business Logic
IF "Connect FFD to POS by selecting Hardware Location..." = enabled THEN;
When launching Pole Display, the POS station identifier will prompt "Hardware Location" selection vs. "Cash Drawer"
This is necessary as card terminals are associated to hardware locations
This will NOT effect cash drawer reporting as the drawer remains attached to the user on the sale
IF "Enable TreezPay on Front Facing Display" = enabled THEN;
Upon checkout, TreezPay SDK initialized surfacing available payment methods
Config Flow: Surface Available Pay Methods - Set Default Provider
In the first build, to set payment type availability in the payment method selection screen of the SDK, the user must set the desired provider of the payment type as DEFAULT within the TreezPay Portal.
Steps
Navigate to TreezPay Portal > Settings > Payment Configuration > {payment Type} tab
Select desired provider for payment routing in SDK from dropdown
Select “Set Default”
ACH ONLY** - Set “in-store ACH” = enabled
Save
Set Default Business Logic
A privileged user can change default provider at any time
By doing so, when the customer selects the payment type it will then route to the terminal of the new default provider
If a user has multiple ACH providers, ensure that ONLY 1 is “in-store ACH enabled”
While two options will appear during ACH payment selection, ONLY the DEFAULT will be able to capture payment
Known v1 limitation
Config Flow: Surface Available Pay Methods - Terminal x Hardware Association
Like POS, in order to ensure payments are being routed to the correct terminal at the corresponding front facing display location, card terminals must be associated with hardware locations.
Steps
Navigate to TreezPay Portal > Settings > Payment Configuration > {payment Type} tab
Select desired provider from the provider dropdown (if more than one)
Select “Add” or “Edit” payment device
Select desired “POS Location” from dropdown
Save
Terminal Association Business Logic
If a card terminal is associated with the SDK hardware location THEN;
The pay type tile will be visible within the pay method selection view & upon payment submission, payment will route through that card terminal
If a card terminal is NOT associated with the SDK hardware location THEN;
that payment method tile will be hidden from the payment method selection view.
Config Flow: Set Display Fee
Setting a display fee for the default provider will surface that fee on the payment method tile to provide transparency to the consumer during payment method selection. As fee assessment is a function of the pay provider, it is important that if the retailer chooses to employ this feature, that they ensure the display fee always reconciles with the pay provider fee.
Steps
Navigate to TreezPay Portal > Settings > Payment Configuration > {payment Type} tab
Select default provider from the provider dropdown (if more than one)
Set “Fee” value in global configuration
Save
Display Fees Business Logic
Fees are not included in pre-pay totals (for now)
Conscious decision as some retailers aim to suggest that this is a pass through cost directly from the payment provider
Most processing fees also show as separate line items on the customer bank statement.
Including fees in the total could cause a mis-match from the sale total and lead to disputes
SellTreez payment fees are NOT currently supported in in this version
Generally speaking, TreezPay team encourages using processor derived convenience fees
Currently, setting display fee to $0 will hide the fee value from the pay method tile
Subject to change post v1
Currently, display fees only support integer, $ values
Subject to change post v1
Config Flow: Set Round Amount (CATM)
To provide increased transparency of expected payment total pre payment, the retailer can now set a “Round Amount” for integrated ATM providers in their TP Portal. Similar to fees, the actual rounding is now primarily a function of the pay provider and occurs on the machine. Again, it is important, if setting this value the retailer ensures it remains accurate with the round amount established with their provider.
Steps
Navigate to TreezPay Portal > Settings > Payment Configuration > {payment Type} tab
Select desired provider from the provider dropdown (if more than one)
Input value for “Rounding Amount”
Save
Round Amount Business Logic
Setting "Round Amount" is only a function of Integrated ATM
"Integrated ATM" = "Rounded Debit" in the customer pay method selection view
Round value is used to surface “est. round” in during pay selection as well as included in the pre-pay total calculation on the pay submission screen
Like fees, setting round value is optional, but HIGHLY recommended to avoid consumer frustration
I.e. IF no round amount set, expect some consumer shock when total mysteriously increases on machine
Config Flow: Enable Pre-Tipping
To align the user experience with traditional retail, the SDK includes a pre-tipping feature. When enabled, this feature allows users to add a tip before completing the payment and see, in real time, how different tip amounts affect the pre-payment total.
Steps
Navigate to TreezPay Portal > Settings > Payment Configuration > {payment Type} tab
Select desired provider from the provider dropdown (if more than one)
Select “pre-tipping” toggle = enabled
Save
Pre-Tipping Business Logic
Only providers that support pre-tipping will have the pre-tip enable option in TreezPay Portal
While all (current) pay providers support tipping, NOT all pay providers support pre-tipping flow
Tip options will be hidden from “Payment Summary” screen if disabled or not provider supported
IF decide to enable pre-tipping THEN disable provider tipping
This will ensure that your customers aren’t prompted to tip twice
Tip inputs will dynamically change the total on the “Payment Summary” screen
Total Calculations: Pre-Tipping & Round Amount Enabled (ATM only)
Business Logic
IF tip amount is less than the cash back amount;
THEN the tip amount comes out of the “Expected Change” && the total stays the same
IF tip amount is greater than the cash back amount;
THEN total rounded to next "round amount" and expected change = difference between next round and amount over the post tip total
Examples: ($10 round amount & $7 pre-tip total)
Ex 1: Customer adds $2 tip → post tip total = $9 → round to next $10 → total charged = $10 → expected change = $1
Ex 2: Customer adds $4 tip → post tip total = $11 → round to next $10 → total charged = $20 → expected change = $9
TreezPay on Front Facing Display User Flows
Card payment workflow
Proceed to checkout screen on POS. You will expect to see a loader on FFD, and then the new payment widget. Payment options that are currently configured will show on the widget.
Select an integrated card payment option, tip amount etc. You should the POS get locked out of doing payments with a corresponding message explaining what the user is doing on FFD.
When you submit the payment in FFD you should see it trigger on the card terminal.
Complete the steps on card terminal; you should see a success message on FFD and a loader on POS, followed by a change screen, on both screens.
Tips have been added to the FFD change screen for card payments, to match the POS change screen
ACH workflow
Proceed to checkout screen on POS. You will expect to see a loader on FFD, and then the new payment widget. Payment options that are currently configured will show on the widget.
Select ACH, and then select the ACH provider that matches your current default ach provider in Treezpay
Wait for a QR code to appear
Scan the QR Code on your mobile device
Proceed through the ACH provider workflow
Once you authorize the payment on your mobile device, you will see a success message on FFD, however on POS instead of a change screen you will now have the option of clicking complete and capture.
Now the POS will go straight into the next ticket with no change screen, the FFD will show a change screen however tips are not shown on FFD change screen for ACH
Cash workflow
Proceed to checkout screen on POS. You will expect to see a loader on FFD, and then the new payment widget. Payment options that are currently configured will show on the widget.
The end consumer can either select "Other" and hand over their cash, or ignore the payment widget and hand over their cash
the bud tender rings up the cash as normal and the change screen shows as normal on both screens
Note: When the bud-tender starts to ring them up in cash or any other payment type, the ffd should get a message covering the screen and be unable to proceed with any payments, we call this the reverse lock
Consumer changes their mind workflow
Proceed to checkout screen on POS. You will expect to see a loader on FFD, and then the new payment widget. Payment options that are currently configured will show on the widget.
The end consumer selects an integrated payment type on the payment widget (any), locking the budtender out of any of their payments
The end consumer changes their mind and wants to pay in cash, they must hit "Other" to re-enable payments for the Budtender
The budtender rings them up in cash and proceeds as normal
Split Payments: (Cash, Rewards as Payment, & Non-Integrated Pay Types)
Proceed to checkout screen on POS. You will expect to see a loader on FFD, and then the new payment widget. Payment options that are currently configured will show on the widget.
POS user to apply split payment before customer starts payment on SDK
As of now, this should be verbally communicated between budtender and end consumer
Payment total decremented by X amount
Payment widget is now locked
POS user completes the sale as Cash or Integrated Payment directly from POS
Known v1 Limitations & Best Practices
Covered most of these in detail above but see below for quick recap of known limitations and best practices
Fees
SellTreez established payment fees NOT currently supported in v1
Payment provider established convenience fees ARE supported
Fees are not included in pre-pay totals
This is because pay provider fees tend to show as a separate line item on customer bank statement
Keeping this out of the pre-payment total will ensure the total the customer sees matches the sales total on their bank statement
Tipping
Pre-tipping on SDK is only a function where provider supported
All current providers support tips BUT not all allow tip value to be sent in on payment request
Tips established on provider side will still be captured and reported in Treez
To ensure the best pre-tipping experience, ensure that tips are turned off at the provider level so the customer is not asked to tip twice
Tips are not currently surfaced back on the POS change screen for ACH in v1
Tips are however logged and visible in reporting
ACH
Only 1 ACH provider can be currently used
If have multiple, ensure that only 1 is set to default && “in-store ach enabled”
Both Treez FFD and POS will only have knowledge of when a customer successfully submits an ACH payment
While the customer has the ability to navigate back from the QR screen, they should not pay with another method if intend on following through with the ACH flow
Upon submitting an ACH payment, the POS user will still need to complete and capture the payment in Treez to finalize the sale
By not doing so, the payment will remain in an “Authorized” state and customer will NOT be charged
Pre-tipping is not currently supported for ACH providers
Tipping is however supported through the ACH provider web app upon scanning the QR
Tips will not surface on the payment success screen for ACH
Tips will however be logged and persist through Treez payment reports
Cards
SDK does not check terminal availability before payment like POS.
Please ensure the terminal is online, in the payment app, and ready to accept payment prior to each new sale
SDK does not have a “cancel” payment on terminal function like POS
To cancel payment on terminal, cancel on terminal directly
SDK and POS will still register if canceled directly on terminal and allow new sale
“Rounded Debit” pay method on front facing display = Cashless ATM
This was determined to be a more consumer friendly name as it better depicts what to expect with this payment
POS x FFD
Split payments should occur before customer initiates integrated payment on the front facing display
The customer can however, select "Other" anytime before initiating the payment allowing the POS user to take a non-integrated form of payment (i.e. cash)
Split payments will lock the FFD and ability for customer to perform integrated payment
POS user must complete the sale if accepting split payment
Upon selecting “Other” pay type, it is NOT possible to reinitialize SDK unless navigate back to cart and checkout again
Expected that if customer selects “Other,” the budtender will take over the sale
The consumer can still pay via integrated payment via budtender pushing payment in POS