Per-transaction settings

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, a SaleRequest, AuthRequest, or PreAuthRequest). Transaction settings work for all subclasses of TransactionRequest, 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:

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:

1. a percentage or amount
2. an isEnabled indicator
3. 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]);

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]);

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]);

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:

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.

Card entry values include:

• CARD_ENTRY_METHOD_MAG_STRIPE
• CARD_ENTRY_METHOD_ICC_CONTACT
• CARD_ENTRY_METHOD_NFC_CONTACTLESS
• CARD_ENTRY_METHOD_MANUAL

If no card entry options are set, all payment methods are presented to the customer by default.

The following image shows the effect of each CardEntryMethod option on the Clover Mini START screen.

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);