# Add SDK Dependency (/global/en/docs/Terminal/CodeDevelopment/Add-SDK-Dependency)

## Add SDK Dependency

#### How to set up the SDK?

Contact our support team to request your Maven repository credentials. Once received, add the credentials to your settings.gradle file to enable repository access.

```
maven {
    url 'https://maven.newlandnpt.com/repository/maven-public/'
    credentials {
        username = System.getenv("NEWLAND_MAVEN_USERNAME")
        password = System.getenv("NEWLAND_MAVEN_PASSWORD")
    }
}
```

In your build.gradle file (app/module level), add the appropriate SDK dependency. Replace `$version` in the examples with the SDK version you selected.

```
// SDK 4.7 and later
implementation('com.newlandnpt.pec:hyperterminal:$version')

// Only applicable when PayExplorer Connect is installed on the device or cross-device communication is not required
//implementation('com.newlandnpt.pec:retailer:$version')

// Legacy SDK versions (4.5 - 4.6)
//implementation('com.newlandnpt.hipos:hipos-hyperterminal:$version')

// Legacy SDK versions (below 4.5)
//implementation('com.newlandnpt.hipos:hi-retailer-android:$version')
```

#### Configure your app

To connect a Bluetooth reader, enable Bluetooth permissions. Add the appropriate permissions to your manifest as shown here:

```
<!-- Bluetooth permissions for non-Newland devices -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH"
    android:maxSdkVersion="30" />

<!-- For applications running on Newland devices, add the following permissions -->
<uses-permission android:name="android.permission.MANAGE_NEWLAND" />
<uses-permission android:name="android.permission.MANAGE_ANALOG_SERIAL" />
```

#### ProGuard Configuration

When building a Release version, to ensure the SDK works correctly, add the following ProGuard rules to your proguard-rules.pro file:

```
# Keep attribute information
-keepattributes SourceFile,LineNumberTable
-keepattributes *Annotation*,Signature,InnerClasses,EnclosingMethod,Exceptions

# Keep SDK callback interface implementations
-keep class * implements com.newlandnpt.nexo.scap.retailer.sdk.framework.Exchange$RetailerSDKCallback { *; }
-keep class * implements com.newlandnpt.nexo.scap.retailer.sdk.framework.Exchange$RetailerSDKErrorCallback { *; }
-keep class * implements com.newlandnpt.nexo.scap.retailer.sdk.framework.Exchange$RetailerSDKResultCallback { *; }
-keep class * implements com.newlandnpt.nexo.scap.retailer.sdk.RetailerManager$EventNotificationCallback { *; }
-keep class * extends com.newlandnpt.hyperterminal.data.setting.items.base.BaseSettingItem { *; }

# Keep serializable classes used by the SDK
-keepclassmembers class * implements java.io.Serializable {
    static final long serialVersionUID;
    private static final java.io.ObjectStreamField[] serialPersistentFields;
    !static !transient <fields>;
    private void writeObject(java.io.ObjectOutputStream);
    private void readObject(java.io.ObjectInputStream);
    java.lang.Object writeReplace();
    java.lang.Object readResolve();
}

# Keep CREATOR for Parcelable implementations
-keepclassmembers class * implements android.os.Parcelable {
    public static final ** CREATOR;
}

# Keep SDK related packages
-keep class android.newland.** {*;}
-keep class com.newlandnpt.nexo.scap.sdkal.** { *; }
-keep class com.newland.nsdk.** { *; }
-keep class com.newland.me.** { *; }
-keep class com.newland.modules.** { *; }
-keep class com.newland.pospp.** { *; }
-keep class com.newland.rficcard.** { *; }
-keep class com.newland.toms.** { *; }

# Keep native methods
-keepclasseswithmembernames class * {
    native <methods>;
}

# Keep classes and members annotated with @Keep
-keep @androidx.annotation.Keep class * { *; }
-keepclassmembers class * {
    @androidx.annotation.Keep *;
}

# Keep ViewBinding related classes
-keep class * implements androidx.viewbinding.ViewBinding {
    public static *** inflate(android.view.LayoutInflater);
    public static *** inflate(android.view.LayoutInflater, android.view.ViewGroup, boolean);
    public static *** bind(android.view.View);
}
-keep class **$ViewBinding { *; }
-keep class **.*Binding { *; }
-keep class **.*BindingImpl { *; }

# Ignore warnings
-dontwarn com.newland.**
-dontwarn newland.google.zxing.**
-dontwarn okhttp3.internal.Util
-dontwarn org.jetbrains.annotations.**
```

**Update Type:** Android SDK optimization update

This release is an optimization update for the Android SDK. It adds custom status fields to event notifications and transaction results. Before upgrading to V4.7.04, review the following breaking changes and update the relevant integration code. This document also summarizes the major breaking changes introduced in V4.7. Integrators upgrading directly from an earlier version to V4.7.04 must also review the V4.7 breaking changes.

**Added**

**1. Custom Status Field in Event Notifications** — Added notificationMessage to EventNotificationParam.

**2. Custom Status Field in Transaction Results** — Added respReason to the transaction result parameter.

**Review of V4.7 Breaking Changes**

The following changes were introduced in V4.7 and are not backward compatible. Integrators that have already upgraded to V4.7 may skip this section:

**(1) Android Maven Coordinate Change** — The Maven group ID has changed from com.newlandnpt.hipos to com.newlandnpt.pec:

- ECR: com.newlandnpt.pec:hyperterminal (previously com.newlandnpt.hipos:hipos-hyperterminal)
- Payment System / Payment Terminal: com.newlandnpt.pec:service (previously com.newlandnpt.hipos:hipos-service)

**(2) documentQualifier: SRCP → MRCP** — SRCP has been replaced with MRCP (Merchant Receipt). Update all code references to SRCP.

**(3) MsgDisplayCapabilities.destination: array\<enum> → Single enum** — Pass a single enum value instead of an array.

**(4) DetailedAmount.amount: ImpliedCurrencyAndAmount Object → String** — The field type has changed from an object to a string. For example: \{ value: "1.00" } → "1.00".

**(5) AccountType.CDBT → CardAccountType3Code.CDBT** — The enum has been standardized in accordance with ISO 20022. Update all enum references accordingly.

**Important Notice**

PayExplorer Connect app upgrade requirement:\
(1) If your ECR app uses SDK 4.7 and communicates via Bluetooth, USB, or UART, please upgrade the PayExplorer Connect app to V4.7.01 or later to ensure stable communication.\
(2) If the acquiring app integrates PayExplorer Connect SDK V4.7.01 or later, the PayExplorer Connect application must also be upgraded to V4.7.01 or later. Otherwise, the SDK will not be able to establish a connection or communicate correctly. Ensure that the SDK and application versions are compatible.

**Update Type:** Android SDK optimization update

This release is an optimization update for the Android SDK. The integrated third-party SDK has been updated to a newer version, with refined certificate validation handling for communication security.

**Added**

**New Transaction Request Fields** — The following fields were added to transaction requests:

- acquireManagerPwd (string) — Administrator password for sensitive operations.
- productLabel — Product label or category identifier.
- taxType — Tax classification for the transaction or line item.

Refer to the relevant API page, such as Payment or Refund, for field availability by interface.

**Improved**

The integrated third-party SDK has been updated to a newer version, with refined certificate validation handling for communication security.

**Important Notice**

PayExplorer Connect app upgrade requirement:\
(1) If your ECR app uses SDK 4.7 and communicates via Bluetooth, USB, or UART, please upgrade the PayExplorer Connect app to V4.7.01 or later to ensure stable communication.\
(2) If the acquiring app integrates PayExplorer Connect SDK V4.7.01 or later, the PayExplorer Connect application must also be upgraded to V4.7.01 or later. Otherwise, the SDK will not be able to establish a connection or communicate correctly. Ensure that the SDK and application versions are compatible.

**Update Type:** Android SDK optimization and breaking changes

This release is an optimization update for the Android SDK. Key changes include simplified Bluetooth permissions and adjusted behavior for Bluetooth MAC address connection failures.

**Breaking Changes**

The following changes are required when upgrading to this version:

**(1) Simplified Bluetooth Permissions**

- **Non-Newland devices**: Only BLUETOOTH\_CONNECT (Android 12+) or BLUETOOTH (Android 11-) is required
- **Newland devices**: Requires additional MANAGE\_ANALOG\_SERIAL and MANAGE\_NEWLAND declarations
- Removed previously required BLUETOOTH\_SCAN, BLUETOOTH\_ADVERTISE, ACCESS\_FINE\_LOCATION permissions

**(2) Bluetooth Permission Request Mechanism**

- Runtime Bluetooth permission request and authorization must be completed before calling any transaction API
- When permission is not granted, the SDK returns error code -1003

**(3) Changed Behavior for Bluetooth MAC Address Connection Failures**

- **Previous**: Service selection screen was displayed when connection timed out or failed
- **New**: SDK returns error code -500 (Failed to connect!) directly, no service selection screen is displayed

**Update Type:** API Improvements & Breaking Changes

This release introduces major API enhancements, data model optimization, and workflow improvements. Key updates include transaction API standardization, receipt output model simplification, enhanced unattended payment support, and improved communication error handling.

**Breaking Changes**

The following API changes may require application updates when upgrading to this version:\
（1）Several deprecated fields have been removed.\
（2）Some data models and field types have been updated.\
（3）Receipt output configuration has been consolidated into a unified model.\
（4）Maven dependency package name change: SDK 4.7 and later versions use new package names com.newlandnpt.pec:hyperterminal and com.newlandnpt.pec:retailer, replacing the old com.newlandnpt.hipos:hipos-hyperterminal.

**Added**

**1. Transaction Context Identifier** — Added AttendanceContextCode to financial transaction requests:\
ATTD — Attended transaction (Default)\
SATT — Semi-attended transaction\
UATT — Unattended transaction\
**2. Extended Device & Payment Information** — Added optional fields to ExchangeRequest:\
orgServiceId — Organization service ID\
orgPkgName — Organization package name

**3. Remote Device Access Information** — Added remote device access fields:\
remoteAccessAddress — Remote access address\
remoteAccessType — Remote communication type

**4. Token-based Payment Support** — Added tokenIdentification in CardAcquisitionResult to support tokenized payment scenarios.\
**5. New Enums** — Added CardDataReadingCode, CardAccountTypeCode, RetailerResultDetailCode, PaymentInstrumentTypeCode, etc.\
**6. Event Notification Extension** — Added new enum parameters to EventToNotify2Code to extend event notification capabilities.

**Changed**

**1. Transaction API Enhancement & Standardization**\
（1）Corrected TipAdjustParam field: totalAmount → tip\
（2）Removed invalid fields:\
ReversalParam.saleItems\
PreAuthParam.amountQualifier\
（3）Updated DetailedAmount structure: amount type changed from ImpliedCurrencyAndAmount to String\
（4）Standardized SaleItems model

**2. Receipt Output Model Simplification**\
（1）Unified receipt output target: replaced DocumentType7Code, UserInterfaceCode, and UserInterface4Code with the unified ReceiptOutputTarget enum\
（2）Simplified MsgDisplayCapabilities model — the following fields changed from list-based to single-value:\
destination\
availableFormat\
availableLanguage

**Improved**

**1. Communication Target Selection Error Handling** — For the following scenarios, the SDK now returns an error result instead of displaying the target selection interface:\
Target unavailable\
Target not found\
Communication timeout\
**2. API Behavior Consistency** — Improved API behavior consistency and error handling experience.\
**3. Internal Architecture** — Optimized MDB workflow architecture and internal state handling, improved transaction workflow consistency for unattended payment scenarios, and enhanced internal communication processing and exception handling mechanisms.

**Important Notice**

PayExplorer Connect app upgrade requirement:\
(1) If your ECR app uses SDK 4.7 and communicates via Bluetooth, USB, or UART, please upgrade the PayExplorer Connect app to V4.7.01 or later to ensure stable communication.\
(2) If the acquiring app integrates PayExplorer Connect SDK V4.7.01 or later, the PayExplorer Connect application must also be upgraded to V4.7.01 or later. Otherwise, the SDK will not be able to establish a connection or communicate correctly. Ensure that the SDK and application versions are compatible.

**Previous Versions**

**Update Type:** API Refinement

**Changed**\
Refined receipt configuration and output options.\
Simplified tip adjustment parameter design.

**Update Type:** Feature Enhancements, Improvements & Configuration Changes

**Changed**\
Updated Maven repository endpoint. It is recommended to use the new public repository for dependency management:\
url '[https://maven.newlandnpt.com/repository/maven-public/](https://maven.newlandnpt.com/repository/maven-public/)'

**Added**\
Device discovery interface to improve connectivity and device management\
Default service configuration for more flexible service selection strategies\
Bluetooth communication support for device connectivity and transaction processing (requires proper permission configuration)\
Multiple target selection modes to support diverse integration scenarios:\
\**Device-based targeting:*\* direct transactions to a specific device via SN\
\**Service-based targeting:*\* bind to a specific service instance\
\**Address-based targeting:*\* initiate transactions via IP or Bluetooth address\
Service selection reset capability with multiple clearing options:\
Clear by device SN\
Clear by service type\
Clear by service category\
New transaction-related interfaces:\
Tip Adjustment\
Reprint

**Improved**\
Enhanced transaction APIs, covering payment, void, refund, and pre-authorization scenarios.\
Improved API consistency and extensibility for better adaptation across regions and business needs.

**Adapted**\
Optimized UI for specific terminal devices to improve display and interaction experience.

**Update Type:** Feature & Bug Fix

**Added**\
Support for simultaneous use of LAN, USB, and UART communication methods.

**Fixed**\
Fixed an issue where refund transactions showed a parameter error when returning.

**Update Type:** Bug Fix

**Fixed**\
Fixed a JSON parsing error caused by duplicate valueAddedTax fields in both parent and child classes.

**Update Type:** Bug Fix & Adaptation

**Fixed**\
Fixed page crashes on the service selection page for certain device models.

**Adapted**\
Adapted to the UART communication channel of N750P.

**Update Type:** Bug Fix

**Fixed**\
Fixed an issue causing app crashes on Android 8.

**Added**\
Added fields additionalSaleData1 and additionalSaleData2 to the request parameters.

**Update Type:** Feature

**Added**\
Exposed field orgIssuerReferenceData in the refund transaction to handle scenarios where the original merchant order number cannot be used for refund processing.\
Added a new field paymentReceipts in the payment transaction response message.