Release v316/316.1

Merge pull request #104 from clover/r316

Release 316

Release v306

The following data model changes, new features, improvements, deprecations, and bug fixes are available in the release of Clover Android SDK v306.

Data model changes

Added classes for ItemOverride, ModifierOverride, and LayoutOverride.

New features and improvements

Added:

• Batch details to the refund details page.
• New column in theorders.order_fee table named service_charge_uuid.

Semi-integration

Enabled printing of TipSuggestion overrides.

Restaurant Solutions

Added:

• defaultPosMenu in response to menu sync API. This lets the device discover if the menu is defaultPosMenu.
• menuId in the menu and category tables.
• Method fireLineItems() to OrderConnector to directly fire the line items to the printer in case of Auto-Coursing.

Payments—Core Processing App

Added a pre-auth start screen to the Station Duo Register app. The screen message instructs the customer to present their card.

Payments

Batched the following reference number details on the refund details page:

• Batch ID
• Batch date and time
• Funding date

Added:

• New attribute when creating pre-auth—Payment.paymentAttribute.createAuth = true in ServiceFeeRequest params.
• New service fee API on Auth server.

Point of sale

Added public helper methods in OrderCalc to use order fee calculation APIs from Calc.

Clover Android SDK

New features and improvements

Updated:

• OrderService and OrderUpdateListeners to support applying or removing order fees from the order.
• Clover Android SDK to allow parameters EXTRA_TRANSMIT_UPC_A_PREAMBLE and EXTRA_TRANSMIT_UPC_A_CHECK_DIGIT to pass when starting a barcode scanner app.

Added:

• Support for orderId in PayRequestBuilder.
• New OrderConnector.capturePreauthorization().
• PAYMENT_TYPE and CREATE_AUTH to PayIntent.
• TipAdjust() builder for TipAdjustRequestIntentBuilder.
• Option to the install_apps.py script to use -s or --serial arguments to specify a device. This is sometimes easier than setting the ANDROID_SERIAL environment variable.

Bug fixes

Added:

• Payment ID to receipt contract.
• isSquareDisplay() method to Platform2 to identify square displays. A display is considered square if its aspect ratio is less than or equal to 4/3rds.

Release v304

SDK 304

clover-android-sdk

Data model changes

The following data model changes, new features, improvements, deprecations, and bug fixes are available since the release of Clover Android SDK v293.

Payments

Added a reason column to the credit_refund table in the orders database. This revision updates the CreditRefund class in com.clover.sdk.v3.payments to support that column.

Restaurant Solutions

Added:

• Classes for multiple menu overrides—ItemOverride, ModifierOverride, LayoutOverride.
• Support for multiple devices for Auto Coursing.
• device_id in the print group POJO and changed it to type string.

New features and improvements

Added:

• New parameter in the RegionalExtras class for the merchant ID for Argentina.
• Orders API for a refund by amount (Transaction App).
  POST /v3/merchants/{mid}/orders/{orderId}/refunds

  {  
    "refunds": { "elements": [{ "amount": 1234, "payment": { "id": "ID1" } }] }
    "includeTip": true
  }

Semi-integration

Added:

• Email marketing opt-in for remote receipts.
• Capability for an integrator to prompt for a receipt for payment, credit, and refund. The developer needs to provide the payment ID and indicate whether it is a merchant or customer-facing prompt.
• TipOptions to CloseoutRequestIntentBuilder.

Payments

• Updated void_on_refund API with deletedTime field changes.
• Added:
  • EXTRA_EMPLOYEE_NAME so that it is returned as an intent data result to apps like payments, which request manager and admin override.
  • Support for tenders for Partial Refund By Amount.
  • Extra constant in CardTransactionConstants for ORIGINAL_AMOUNT for partial payment card transaction.
  • New void reason USER_CANCEL_SYNC for a synchronous void call.
  • RequestTip intent builder for prompting a customer for an on-screen tip amount.
  • MANAGER_ID and MANAGER_NAME to payIntent.
  • addAuthorization to OrderConnector.
  • TenderOptions to PaymentRequestIntentBuilder.
  • Ability to retrieve open payments through the Payments API.
  • labelKey field in the anomaly_reasons_avsc in the schema-tool for locale support and merchant reference and updated the AnomalyReasons.java artifact in clover-android-sdk.
• Removed VoidPreauthRequestIntentBuilder and PaymentRefundRequestIntentBuilder to use ReversePaymentRequestIntentBuilder.

Point of sale

Updated addItem broadcast Intent to send a broadcast when items are removed from an order. The broadcast contains a list of line-item universally unique identifiers (UUIDs) and their corresponding inventory-item UUIDs, the same as when items are added to an order. This feature does not require the receiving app to be running to get the notification.

Clover Android SDK

Updated the Clover Android SDK to allow parameters EXTRA_TRANSMIT_UPC_A_PREAMBLE and EXTRA_TRANSMIT_UPC_A_CHECK_DIGIT to pass when starting a barcode scanner app.

Android apps

Clover may temporarily block or permanently remove Receipt Registration providers who repeatedly fail to respond. Make sure your Receipt Registration provider responds within the documented time limit of two seconds.

Bug fixes

Payments

• Fixed an issue where the manual entry option was missing on some devices. Revised PayIntent for Payments manual card entry without EBT tender selection from custom tender buttons.
• Added EXTRA_EXIT_IN_CUSTOMER_MODE to have Billsplit enable CustomerMode on a normal successful exit.
• Removed the deprecated warning from EXTRA_ORDER_ID. It is not deprecated.

Release v293

SDK 293

clover-android-sdk

Data model changes

• Added partner_tax to the tax_type enum to display partner taxes (non-editable by the merchant).

New features and improvements

Payments API

• Updated OrderStateService and OrderStateReceiver classes to enable next-gen modeled customer identification process.

Added:

• TipAdjustRequestIntentBuilder to allow tip adjustment on an existing pre-auth and capture the payment for the final amount.
• RetrieveCreditRequestIntentBuilder class to retrieve a previously processed credit on a Clover device.
• creditId and refundId parameters to RetrieveCreditRequestIntentBuilder.

Semi-integration

• Removed static class from SessionContentObserver to static designation.

Bug fixes

Payments

• Defined ‘PURCHASING_CARD’ to the Module enum.
• Added remoteReceipts to enable or disable print/SMS/email receipts instead of cloverShouldHandleReceipts.

Release v292

SDK v292

clover-android-sdk

Data model changes

Payments

• Added captured parameter to CardTransaction to check for preauth capture.
• Updated v3.payments.Payment.java to include voidReasonDetails and created class VoidReasonDetails.java.

Point of Sale

Added:

• parentLineItemEvent in LineItemEvent.java file to add support to display combined order on the kitchen display system (KDS) app.
• Callback onLineItemModificationsDeleted() method for deleting a modification in OrderUpdateListener.
• printTime field to PrintGroup.java.
• New classes - OrderChangeReasonList and OrderDeleteReason.

Semi-integration

• Added TIP_AMOUNTS constant.

New features and improvements

Payments

• Added Extra_Refund_Reason (clover.intent.extra.Refund_Reason) to convey the merchant-chosen string into the secure pay flow.
• Improved the AuthenticateEmployeeTestActivity.java example.
• Updated voidReasonDetails field to VoidReasonDetails object, which is equal to the same string being generated in the Payment's JSON representation.

Payments API

Added:

• ReadCardRequestIntentBuilder for reading card data support.
• receiptOptions parameter to CreditRequestIntentBuilder.
• ManualRefundRequestIntentBuilder for manual refund requests.
• taxAmountto PaymentRequestIntentBuilder to support adding tax amount.
• IncrementalAuthRequestIntentBuilder.java.
• RetrievePendingPaymentsRequestIntentBuilder component. This component allows a user to get a list of all payments accepted while offline, and not yet processed; so that offline events can be reconciled with the funding total.

Point of Sale

Added:

• Retrofit converters for Clover SDK objects.
• OrdersChangeReason class to capture anomalies in order change or cancellation.

Semi-integration

• Added CashbackSuggestion object to TransactionSettings

Bug fixes

Device

• Added a warning that Extra_Show_Preview is not supported on Flex 1 devices.

Payments

• Updated Merchant_Reason to VoidReasonCode. The VoidReasonCode uniquely identifies VoidReasonDetails that appears when a merchant selects a configured reason when issuing a void.
• Fixed an issue where terminal ID (TID) is not displaying on the Cash Terminal receipt and Cash Web receipt for both, Sale and Refund.

Release v288

SDK v288

clover-android-sdk

Data model changes

Payments API

• Renamed EMV to CHIP in CardEntryMethod class.

New features and improvements

Payments

• Added deleted_time and sort_order columns fields to AnomalyReasons class (clover/sdk/v3/payments/AnomalyReasons.java).

• Updated /v1/Intents.java with public static final String EXTRA_USE_CONNECTED_DEVICE = "clover.intent.extra.USE_CONNECTED_DEVICE".
  Used to choose between paying on connected device and local device. The intent is set with boolean true for EXTRA_USE_CONNECTED_DEVICE if the merchant requested payment on connected device.

Payments API

• Added TokenizeOptions class to PaymentRequestIntentBuilder and PreauthRequestIntentBuilder. The TokenizeOptions class contains a single property, suppressConfirmation. However, the presence of TokenizeOptions, regardless of the suppressConfirmation value, indicates that a token for the payment card used should be generated. The tokenize option is secondary to the payment; therefore, a failed tokenization could still result in a successful payment but a failed payment will not result in a successful tokenization.

Quick Service Restaurant

• Added FulfillmentEvent to the Order object to accommodate order fulfillment status.

Bug fixes

• Fixed an issue where enum-parsing exceptions were occurring when consuming a plan payload from APIs. We updated the COS plan type to add new Payments to the android SDK types.

Release v284

SDK v284

clover-android-sdk

New features

• Added deleteCategories method to InventoryTestActivity.java to improve the performance of bulk delete items operation.
• Added getItemsForModifierGroup to the InventoryConnector class to identify items associated to a modifier group.
• Added OrderContract.OrderSummary API for improved search performance and longer history.
• Added updateCategoryItems method to update only category items.
• Added updateCategorySortOrders method to support bulk update sorting orders.
• Added the following APIs to provide access to printer on a merchant's device:
  • POST /v3/merchants/{mId}/print_event (requires the Write orders permission)
  • GET /v3/merchants/{mId}/print_event/{eventId}(requires the Read orders permission)
• Added the following methods to simplify registering and unregistering of the CustomerMode broadcast receiver. The methods will check whether it is appropriate to register/unregister given the context.
  • register(Context)
  • unregister()
• Added the following functions to TenderConstants for merchants to manage PayPal/Venmo refunds same as the credit/debit refunds.
  • isPayPalVenmo()
  • isSystemPayPal()
  • isSystemVenmo()
• Added TX_ACTION to TX_ACTION_UPDATE_AUTH to ask for the card details at the terminal while updating a pre-auth request.
• Added bulkAssignColorToItems method to InventoryConnector class to assign category color to inventory items that belong to a particular category.
• Added CONTENT_WITH_MENU_URI to InventoryContract class to help fetch menu data with category.
• Added MERCHANT_ONLY API to Platform2.java to determine if the device is intended for merchants.
• Added TokenizeCardRequest and TokenizeCardResponse classes in PayIntent.java for token request and response.
• Added addServiceCharge2 function to OrderV31Connector.java to indicate if the service charge was automatically applied to the order.
• Added bulkLineItemEvent.insert method to LineItemEventContract.java.
• Added the following functions to PayIntent.java:
  • isManualCardEntryByPassMode - if enabled, on starting the payment in manual flow, the device prompts for card number
  • isAllowManualCardEntryOnMFD - if enabled, for manual entry, the card information can be added on the merchant-facing device

Data model changes

• The pre-auth payment request allows both incrementing and decrementing of amount.
• Added two columns to item and one column to modifier for auto-management of item availability.
• Added a tag to Merchant Plan to support Essentials.
• Added FLAG_NO_TIP int to PrintJob.java.
• Added OFFLINE status to support unsubscription.
• Added TEST_PRINT enum to PrintCategory.java to support the Test Print feature.
• Added dccEligible field to V3 DCCInfo class.
• Added EXTRA_NO_TIP string to Intents.java to block capturing of tips in the print receipts.
• Added the following columns to ItemColumns to help fetching MenuItem with item:
  • On point-of-sale (POS)
  • Online
  • Stock
• Added ItemColor column to LineItem class.
• Added DINE_IN service type to ServiceType.java.
• Added Network Transaction ID to CardTransactionConstants for printed receipts.
• Added Quickpay UUID to PayIntent to be used by SecurePayService to finalize a payment.
• Added flatTip field to TipSuggestion.java.
• Added cashbackAmount parameter to PayIntent class, which allows cashbackAmount for the SecurePaymentFlow.
• Added cardlessType, count, and total fields to BatchCardlessTotal.java.
• Added trialDaysLeft field to App.java to show the trial days remaining for the app installed.
• Added weightedRating field to AggregateRating.java to retrieve apps by ratings.
• Added isPresentQrcOnly field to PayIntent for QR scan.

Replaced intents

• The Payment Connector interface replaces ACTION_SECURE_PAY, ACTION_STATION_PAY, and ACTION_STATION_SECURE_PAY APIs.
• The ACTION_AUTHENTICATE_EMPLOYEE API replaces the ACTION_REQUEST_ROLE API.

Deprecated/removed

• OrderContract.OrderSummaries API.
• Product Code and SKU columns.
• ACTION_REQUEST_ROLE API.
• DeviceCountInfo and DevicePriceInfo APIs.

Emulator setup in Android Studio

Python 3.5 or later version is required to run the ./install_apps.py script, refer to Installing required Clover merchant apps.

Release 262.2

SDK v262.2

clover-android-sdk

Data model changes

• AdditionalChargeAmount - added the rate field and associated methods
• AdditionalChargeType - added CONVENIENCE_FEE, CREDIT_SURCHARGE, and INTERAC_V2 charge types. The INTERAC type is deprecated.
• Added the IdArray class
• DisplayOrder - added the isVat field and associated methods
• Payment - added the DISCOUNT and OFFLINE_RETRYING result statuses
• PrintState - added PRINTING state
• VoidedLineItem - added the approvedBy field and associated methods

New features

• When working with an order, apps can create and display manager overrides for voided line items using the new approvedBy field.
• Information about merchant-set additional charges on a credit transaction can be accessed using AdditionalChargeAmount.getRate. Apps displaying transaction details or printing custom receipts will need to be updated to show any fees (returned in the additionalCharges of the JSON response).
• The SDK’s cash drawer APIs were adjusted to make it easier for apps to connect to and use external cash drawers or those built into Clover devices. In the future, this will make it easier and faster for Clover developers to support new models of native and external cash drawers. The updated CashDrawer and CashDrawers classes provide functions for working with Clover-printer-connected and external drawers, respectively.
• The ACTION_KEYPAD action was added to provide a consistent way to take customer input on Clover devices. The keypad can be one of three types: numeric, email, or phone. See the documentation for complete details.
• OrderV31Connector now has methods to allow you add line items in bulk: addFixedPriceLineItems, addPerUnitLineItems, and addVariablePriceLineItems.

Deprecations and removals

Additional charges

In AdditionalChargeType, the INTERAC charge type is deprecated and should be replaced with INTERAC_V2.

Cash drawers

Several hardware-specific cash drawer classes are deprecated in favor of the more general CashDrawer and CashDrawers:

• APG554aCashDrawer
• MiniPrinterCashDrawer
• Station2018PrinterCashDrawer
• StationPrinterCashDrawer

The ACTION_OPEN_CASH_DRAWER_SERVICE action and the v1.printers.CashDrawer class are now deprecated.

EmployeeConnector

• Usages of the setEmployeePin method should be replaced with updateEmployee
• Usages of the logout method should be replaced with Lockscreen.lock

Equipment

The Equipment class has been removed from the SDK.

Intents

Usages of the ACTION_MANUAL_PAY and ACTION_MANUAL_REFUND actions should be replaced with ACTION_CLOVER_PAY.

InventoryConnector

The following methods have been deprecated:

• getItems()
• getItemsWithCategories()
• getItemIds()
• getItems(ServiceConnector.Callback<List<Item>> callback)
• getItemsWithCategories(ServiceConnector.Callback<List<Item>> callback)
• getItemIds(ServiceConnector.Callback<List<String>> callback)

Item

Usages of the getStockCount method should be replaced with getItemStock.

ItemStock

Usages of the getStockCount method should be replaced with getQuantity.

Merchant

• Usages of the getPhoneNumber method should be replaced with Address.getPhoneNumber.
• Methods associated with merchant equipment have been removed:
  • clearEquipment
  • getEquipment
  • hasEquipment
  • isNotEmptyEquipment
  • isNotNullEquipment
  • setEquipment

OrderV3Connector

Usages of OrderV3Connector should be replaced with OrderV31Connector.

OrderV31Connector

Usages of the deleteLineItemsWithReason method should be replaced with deleteLineItems2.

Platform

The previously deprecated Platform class has been removed from the SDK.

Service charges

Usages of the ServiceCharge.getPercentage method should be replaced with ServiceCharge.getPercentageDecimal.

clover-android-sdk-examples

The following samples have been created or updated for v262.2:

• Added a new Cash Drawers Test example showing how to use the SDK to work with built-in and external cash drawers
• Added a new Keypad Test example showing the usage of the new keypad intent
• Fixed a bug in the Print Task example that would cause the app to crash

Release 248.4

SDK v248.4

clover-android-sdk

Data model changes

• Order - added externalReferenceId
• TransactionInfo - added cardEntryType and clientCardType

New features

• The SDK has been migrated to AndroidX
• Two methods were added to OrderCalc: getTotalBeforeRefunds and getTaxSummariesBeforeRefunds
• Your app can perform needed cleanup tasks before it is uninstalled with the APP_PRE_UNINSTALL service intent. See the developer docs for complete information.
• Using the Platform2 class, you can now check if a Clover device has USB ports with the clover.hardware.usb_device_ports system feature.
• The /scripts directory now contains a Python script that can be used in place of the App Updater app when setting up an emulator. See Emulator setup on Android Studio (scripted app install) for complete instructions.

Deprecations

• The APP_INSTALL_DONE intent has been changed from a service intent to a broadcast intent. Apps using the APP_INSTALL_DONE intent should be updated to respond to the explicit broadcast as described in Running app tasks on installation

clover-android-sdk-examples

The following samples have been created or updated for v248.4:

• Added Platform2DetailsActivity.java to show usage of the USB port system feature
• Added example usage of the APP_INSTALL_DONE broadcast intent
• Added example usage of the APP_PRE_UNINSTALL service intent

clover-android-connector-sdk (Payment Connector)

Data model changes

These changes allow Payment Connector apps to pass an invoice, purchase order, or other external identifier with the transaction request.

• AuthRequest - added externalReferenceId
• BaseTransactionRequest - added externalReferenceId
• ManualRefundRequest - added externalReferenceId
• PreAuthRequest - added externalReferenceId
• SaleRequest - added externalReferenceId
• TransactionRequest - added externalReferenceId

Release 228.3

SDK v228.3

clover-android-sdk

Data model changes

The following objects were updated:

• CardTransaction - added currency
• CreditRequest - added paymentCard
• IdentityDocument - added id, createdTime, modifiedTime, deletedTime, and payment
• Payment - added attributes
• PendingPaymentEntry - added externalId and tipAmount
• TipSuggestion - added amount (as an alternative to percentage)
• TransactionInfo - added emergencyFlag and reversalStandRefNum

New features

• The ImagePrintJob2 class was added to replace the now-deprecated ImagePrintJob. The new class does not use the device’s built-in storage, so merchants will not need to do anything to remove old image data.
• The Lockscreen class was added to make it easier for apps to lock and unlock the device programmatically. The EmployeeConnector#login() and EmployeeConnector#logout() methods have been deprecated and should be replaced with Lockscreen#unlock() and Lockscreen#lock(), respectively. You can see a basic implementation in the examples repo: LockScreenTestActivity.java
• New methods were added to OrderCalc. getPriceWithoutVAT() and getPriceWithVAT() allow you to more easily retrieve line item pricing data when an item can be sold with or without VAT. getServiceChargeBeforeRefunds() returns the gross service charge. getLineExtendedPrice() returns the line item price without any discounts or modifiers.
• The SDK now contains a full content provider contract for inventory. See com.clover.sdk.v3.inventory.InventoryContract for more information.
• StaticReceiptPrintJob was updated so receipt footer images can be added from a URI.
• A ServiceFeeConnector was added to allow payment apps to easily perform two fee-related actions: payServiceFee and refundServiceFee. See the documentation for complete details: ServiceFeeConnector.

Deprecations

• The CashDrawer#open methods have been deprecated because calls to these methods fail silently or crash applications in some cases. New CashDrawer#open2 methods have been added as replacements. Be sure to read the CashDrawer documentation for the new methods and understand what the return values indicate.
• The EmployeeConnector#login and EmployeeConnector#logout methods have been deprecated and should be replaced with Lockscreen#unlock and Lockscreen#lock, respectively.

clover-android-sdk-examples

The following samples have been created or updated for v228.3:

• Lockscreen (android/sdk/examples/LockScreenTestActivity.java)
• Order with custom items (android/sdk/examples/CustomItemTestActivity.java)
• Printers (android/sdk/examples/PrintTaskTestActivity.java)
• Receipts from URIs (android/sdk/examples/ImagePrinterActivity.java)

clover-android-connector-sdk (Payment Connector)

Data model changes

The following objects were updated:

• TransactionType - added nine new constants