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')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" />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:
(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:
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
(2) Bluetooth Permission Request Mechanism
(3) Changed Behavior for Bluetooth MAC Address Connection Failures
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.
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/'
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.