Additional Resources

Custom Tenders

Overview

Custom tenders allow developers to build out additional payment experiences that are able to be launched on a customer-facing Clover device or as a merchant-facing experience. These new user flows allow for additional payment methods, such as enabling QR scanning, to exist for a given merchant.

This tutorial walks through the process of creating an app that can create a custom tender type and also implements a payment flow that can be initiated from the Register, Sale, and Secure Payment apps.

Note

Create a Custom Tender app

This tutorial assumes that you are already familiar with creating an Android app for Clover devices. For reference on how to do so, please go here: Create Your First Android App

Note

Setup used for this tutorial:

JVM 1.8.0

Gradle 2.3

Android Studio 1.3.2

This app is split into two sections:

Initializing a custom tender for a merchant

Linking into the Register, Sale, and Secure Payment apps

Part One

For this part of the tutorial, we will be using the TenderConnector to initialize our custom tender for our merchant. The base code that is necessary to do so is below, however, production-ready code must also be able to handle error messages and properly inform the user.

Note

The app must be run once before being able to use a custom tender, as the initialization code must be executed in order to register the tender with the merchant. It is recommended to run the custom tender app right after it has finished installation on your Clover device. Please note the initialization in the example code:

tenderConnector.checkAndCreateTender(...)

Important

Don’t forget to add the SDK as a dependency in your build.gradle file.compile 'com.clover.sdk:clover-android-sdk:latest.release'
Also, make sure to add the necessary Android permission to your AndroidManifest.xml.uses-permission android:name="android.permission.GET_ACCOUNTS"

Part Two

There are two different payment experiences that you can choose to implement depending on your specific use case.

If you want a purely merchant-facing payment, such only allowing the merchant to scan a QR code or enter a customer’s phone number for something like a digital wallet redemption, then proceed with Merchant-Facing Setup below.

If you want to develop a customer-facing experience that would launch from within the Secure Payment app on either a Mobile or Mini (1 device use case), or on a tethered Mini (2 devices use case). In this case, proceed to Customer-Facing Setup.

Note

In some cases, it may make sense to allow the merchant to be able to use either method, such as the phone number example above. Please develop your merchant/customer experience and UI accordingly.

Important

Make sure to add setResult(RESULT_CANCELED) in onCreate to create a default exit result.

Merchant-Facing Setup

Below is the basic setup of an activity for a merchant-facing custom tender.

Note

You may also use a logo in the Sale app, instead of your custom tender’s name, by declaring a MERCHANT_TENDER_IMAGE meta-data for the same activity the intent-filter was declared for and referencing your logo asset. It must be solid gray according to the design guidelines.

Note

You may also use a logo, instead of your custom tender’s name, by declaring a CUSTOMER_TENDER_IMAGE meta-data for the same activity the intent-filter was declared for and referencing your logo asset. It must be solid white according to the design guidelines.

Please note that a fullscreen Android theme must be applied (Theme.Holo.Light.NoActionBar.Fullscreen in this example) for a customer-facing experience in order for the UI to appear smoothly before onCreate(Bundle savedInstanceState) is called by the system.

Custom Tender: Customer Facing button in Secure Payments

Partial Payment

If the merchant is on a plan that supports the Register app / Payments app flow (eg. Register and Register Lite), it allows for paying partially. The Sale app on Payment Plus Plan does not.

You can make partial payment by responding with an amount, which can be less than the total amount. Please see the docs for ACTION_MERCHANT_TENDER in the class Intents in the Clover Android SDK.

In addition, you’ll need to account for are refunds on partial payments made by custom tenders. LineItem-level refunds using Custom tenders are possible (i.e., they are not all-or-nothing). First, ensure your custom tender’s Refund Activity can handle refund Intents:

Note

When a lineItem-level, custom tender refund Intent is fired, the EXTRA_AMOUNT is the sum of the lineItems.amounts that were selected. As such, the EXTRA_AMOUNT might be greater than the amount that was paid for using the custom tender. For Orders on which the refund’s EXTRA_AMOUNT <= the custom tender payment, everything will work as intended. However, you’ll still need to add logic to verify this and handle cases where the custom tender was applied as a partial payment, and pass back the appropriate EXTRA_AMOUNT to Clover before finish()-ing.