Beginning with version 1.2.0 of the SDK, you can override certain merchant-level settings for specific transactions. These per-transaction settings give you greater control over tips, signatures, receipts, duplicate transaction logic, offline payments, payment confirmations, and other functions.
Regional rules and inherited settings
For each transaction, several checks are applied by the device to ensure the correct customer-facing screens are displayed. Generally, transaction settings override any device-specific or merchant-configured settings. The exception to this is if the merchant is operating in a region where certain rules cannot be overridden due to legal or regulatory requirements.
For example, some SignatureEntryLocation
options are overriden by regional rules. The following sample shows that sale transactions are set to not require a signature.
private SaleRequest setupSaleRequest() {
SaleRequest saleRequest = new SaleRequest();
saleRequest.setExternalId(ExternalIdUtils.generateNewID());
saleRequest.setAmount(2000L);
saleRequest.setSignatureEntryLocation(DataEntryLocation.NONE);
return saleRequest;
}
If this request was processed by a US merchant, the signature screen would not appear in the payment flow. If the request was processed in Argentina, a regional rule requiring signatures would be applied, and the signature screen would appear despite the transaction setting.
The following image shows how various checks are made against transaction settings. In this flow, the regional rules checked in the final step override any other settings that would otherwise apply to the transaction.


IMPORTANT
To use transaction settings, you must instantiate a subclass of
TransactionRequest
(that is, aSaleRequest
,AuthRequest
, orPreAuthRequest
). Transaction settings work for all subclasses ofTransactionRequest
, but each may only allow the modification of some settings. Support for each setting may also be different for each SDK. Refer to the API documentation for complete details.
Tips
TipMode (TipMode enum)
The tipMode
setting specifies the location from which to accept the tip. You can also omit the tip. Possible values include:
Value | Description | Request Methods | Devices |
TIP_PROVIDED |
The tip amount is included in the request. You must also set the TipAmount field on the request. |
SaleRequest |
Clover Flex, Clover Mini, Clover Mobile, and Clover Station |
ON_SCREEN_BEFORE_PAYMENT |
The tip screen is shown on the Clover device before payment. | SaleRequest |
Clover Flex, Clover Mini, and Clover Mobile |
ON_SCREEN_AFTER_PAYMENT |
The tip screen is shown on the Clover device after payment. | AuthRequest |
Clover Station or Clover Station 2018 |
NO_TIP |
A tip will not be requested for the payment (the tip screen is skipped during the payment flow). This setting will override the merchant setting for tips. | SaleRequest |
Clover Flex, Clover Mini, Clover Mobile, and Clover Station |
TippableAmount (Long)
This option sets the amount to use when calculating tips. This setting is useful if you want to present customers with the option to tip for a portion of the total. When the ADD_TIP
screen appears during payment, this amount is shown in the Tip based on
field.
saleRequest.TippableAmount = 2000L;
TipSuggestions (Array)
This setting allows you to override the default amounts and labels for tip suggestions that appear on the ADD_TIP
screen. Each suggestion can set three values:
- a
percentage
oramount
- an
isEnabled
indicator - a
name
label
You can include a maximum of four suggestions. The following examples show different numbers of suggestions and the resulting screens.
const tipSuggestion1 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion1.setPercentage(18);
tipSuggestion1.setIsEnabled(true);
tipSuggestion1.setName("Acceptable");
const tipSuggestion2 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion2.setPercentage(20);
tipSuggestion2.setIsEnabled(true);
tipSuggestion2.setName("Good");
const tipSuggestion3 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion3.setPercentage(25);
tipSuggestion3.setIsEnabled(true);
tipSuggestion3.setName("Great");
const tipSuggestion4 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion4.setPercentage(30);
tipSuggestion4.setIsEnabled(true);
tipSuggestion4.setName("Excellent");
saleRequest.setTipSuggestions([tipSuggestion1, tipSuggestion2, tipSuggestion3, tipSuggestion4]);


Four custom tip percentage suggestions
const tipSuggestion1 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion1.setPercentage(15);
tipSuggestion1.setIsEnabled(true);
tipSuggestion1.setName("Good");
const tipSuggestion2 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion2.setPercentage(20);
tipSuggestion2.setIsEnabled(true);
tipSuggestion2.setName("Great");
saleRequest.setTipSuggestions([tipSuggestion1, tipSuggestion2, null, null]);


Two custom tip percentage suggestions
If the merchant wants tip options in whole dollar amounts, you can set an amount instead of a percentage.
const tipSuggestion1 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion1.setAmount(100);
tipSuggestion1.setIsEnabled(true);
tipSuggestion1.setName("Acceptable π");
const tipSuggestion2 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion2.setAmount(200);
tipSuggestion2.setIsEnabled(true);
tipSuggestion2.setName("Good π");
const tipSuggestion3 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion3.setAmount(300);
tipSuggestion3.setIsEnabled(true);
tipSuggestion3.setName("Great π");
const tipSuggestion4 = new clover.sdk.merchant.TipSuggestion();
tipSuggestion4.setAmount(400);
tipSuggestion4.setIsEnabled(true);
tipSuggestion4.setName("Excellent π");
saleRequest.setTipSuggestions([tipSuggestion1, tipSuggestion2, tipSuggestion3, tipSuggestion4]);


Four custom tip amount suggestions
The No Tip and Custom buttons cannot be disabled or overridden with this setting.
Signatures
SignatureThreshold (Long)
This setting enables you to override the merchant-configured signature threshold. This threshold is the minimum amount for requiring a customer signature.
For example, to require a signature for any transaction greater than $25.00, set the SignatureThreshold
to 2500
:
saleRequest.SignatureThreshold = 2500;
To require a signature for any amount, set the SignatureThreshold
to 0
:
saleRequest.SignatureThreshold(0);
You can also set SignatureEntryLocation
to NONE
to override the signature threshold entirely so that a signature is never required.
SignatureEntryLocation (DataEntryLocation enum)
This setting enables you to override the merchant-level Signature Entry Location. The possible values are:
Value | Description |
---|---|
| Takes the signature on the Clover device's screen |
| Takes the signature on the paper receipt |
| Skips the signature request for the transaction |
For example, to force the Clover device to take the signature on-screen, you would use:
saleRequest.SignatureEntryLocation = DataEntryLocation.ON_SCREEN;
AutoAcceptSignature (Boolean)
This setting enables you to automatically accept a signature (on screen or on paper) for the given transaction, if applicable. The override prevents the SDK from transmitting signature confirmation requests back to the calling program. The transaction continues processing as if the caller initiated an acceptSignature()
request:
saleRequest.AutoAcceptSignature = true;
Receipts
DisableReceiptSelection (Boolean)
This setting bypasses the customer-facing receipt selection screen. For example, you may want to use this setting if you plan to print receipts from a non-Clover printer: saleRequest.DisableReceiptSelection = true;
Duplicate checking
DisableDuplicateChecking (Boolean)
This option bypasses logic that checks for potential duplicate transactions (payments made with the same card type and last four digits within the same hour) and asks the merchant to confirm acceptance of the payments.
Disabling duplicate checking will make your transactions faster. However, you should only implement this setting if you're willing to accept the risk associated with a potential duplicate payment. saleRequest.DisableDuplicateChecking = true;
Offline payments
The Clover device records offline payments when a merchant attempts a transaction without a network or Wi-Fi connection. In this scenario, the device also can't verify the payment gateway or check if the card is valid and has sufficient funds.
By default, Clover Station, Station 2018, Mini, Mobile, and Flex are set to take offline payments for up to seven days. Merchants can disable offline payments if they don't want to accept the associated risk, or they can set limits for offline payments based on the transaction amount or the total amount processed in an offline state. See the merchant help page for more information.
Overriding merchant settings for offline transactions
The Remote Pay SDK provides three settings that can override the merchantβs settings for offline payments. The settings can be understood by the level of risk the merchant must accept if an offline payment is eventually declined.
IMPORTANT
Allowing any offline payment with one of the following per-transaction settings overrides any merchant-configured limits on these riskier transactions. This includes the limit on days before going online, as well as the amount limit on each transaction and the total offline payments limit.
By using any of the offline payments settings, you assume responsibility for warning the merchant of any possible risk and enforcing any limits on offline transactions required for the merchant.
AllowOfflinePayment (Boolean) - Least risk
If the merchant disables offline payments, setting AllowOfflinePayment
to true
overrides the merchant's settings. If the device is offline and a payment is attempted, the merchant will be prompted to accept or decline the payment with an offline challenge. In the following example, the saleRequest
is set to allow an offline payment if the device cannot connect to the payment gateway:
saleRequest.AllowOfflinePayment = true;
ApproveOfflinePaymentWithoutPrompt (Boolean) - More risk
When the value for this setting is true, offline payments are approved without a challenge. In this case, the merchant may not know that a payment was taken offline. Transactions can be finished faster using this setting, but you should only implement this setting if you are sure the merchants using your integration are willing to accept the risk associated with offline payments.
saleRequest.ApproveOfflinePaymentWithoutPrompt = true;
NOTE
You can also confirm offline payments automatically with the
AutoAcceptPaymentConfirmations
per-transaction setting.
ForceOfflinePayment (Boolean) - Most risk
The device takes payments offline regardless of connection status, and overrides any offline payment limits set by the merchant. The device processes transactions more quickly because it doesn't prompt the merchant to accept or reject the payment. For merchants that need to complete transactions as quickly as possible, this setting may be useful. You should only implement this setting if you are sure the merchants using your integration are willing to accept the risk associated with offline payments.
saleRequest.ForceOfflinePayment = true;
Payment confirmation settings
AutoAcceptPaymentConfirmations (Boolean)
This setting enables you to automatically accept any payment confirmation requests triggered by challenges encountered at the payment gateway (for example, an offline payment or potential duplicate payment). The override prevents the SDK from transmitting payment confirmation requests back to the calling program. The transaction continues processing as if the caller initiated a confirmPayment()
request.
Automatically accepting payment confirmation requests will make your transactions faster. However, you should only implement this setting if you're willing to accept the risk associated with offline payments and potential duplicate payments:
saleRequest.AutoAcceptPaymentConfirmations = true;
Other functions
DisableCashback (Boolean)
This setting disables cashback functionality:
saleRequest.DisableCashback = true;
DisablePrinting (Boolean)
This setting disables automatic printing of receipts for transactions:
saleRequest.DisablePrinting = true;
DisableRestartTransactionOnFail (Boolean)
This setting prevents the Clover device from restarting a transaction that times out or is declined:
saleRequest.DisableRestartTransactionOnFail = true;
CardEntryMethods
This option sets the card entry options presented to the customer on the start screen. If it is not set, the default values (CARD_ENTRY_METHOD_MAG_STRIPE
, CARD_ENTRY_METHOD_ICC_CONTACT
, and CARD_ENTRY_METHOD_NFC_CONTACTLESS
) are used.
The following image shows the effect of each CardEntryMethod
option on the Clover Mini START
screen.


Card entry methods
To allow manual card entry in addition to the default methods, add CARD_ENTRY_METHOD_MANUAL
. If you are using Remote Pay Cloud or Payment Connector, you can also set CARD_ENTRY_METHODS.ALL
.
NOTE
For compliance reasons, card information can only be entered on the Clover device; you cannot enter card information for the customer on your POS and then pass it to the device.
saleRequest.setCardEntryMethods(CloverConnector.CARD_ENTRY_METHOD_MANUAL |
CloverConnector.CARD_ENTRY_METHOD_MAG_STRIPE |
CloverConnector.CARD_ENTRY_METHOD_NFC_CONTACTLESS |
CloverConnector.CARD_ENTRY_METHOD_ICC_CONTACT);
saleRequest.setCardEntryMethods(CARD_ENTRY_METHODS.ALL);
You can also allow a specific combination of entry methods by setting the values required by your merchants. For example, to only allow EMV and contactless entry (and therefore disallow magstripe and manual entry), set the values as in the following example.
saleRequest.setCardEntryMethods(CardEntryMethods.CARD_ENTRY_METHOD_ICC_CONTACT|
CardEntryMethods.CARD_ENTRY_METHOD_NFC_CONTACTLESS);
Updated 21 days ago