N2Tap Embedded Payment SDK

https://docs.neurogine.com
Admin
N2Tap is a secure, production-ready payment SDK for React Native and Flutter that enables simple...
Tokens:29,632
Snippets:220
Trust Score:5.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Initialize SDK, Setup, and Launch Sale in MainActivity

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Sets up the MainActivity to initialize the SDK, perform setup, and then launch a sale transaction upon successful SDK initialization. It uses coroutines to asynchronously wait for the init status.

```kotlin
import kotlinx.coroutines.flow.first

class MainActivity : AppCompatActivity() {
    private val launcher = registerForActivityResult(
        NGHeadlessActivity.contract(ClientHeadlessImpl::class.java)
    ) {
        Log.d(TAG, "onCreate: NGWrappedResult<Transaction>: $it}")
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        lifecycleScope.launch {
            // wait for the first sdk init signal
            when (val initStatus = (application as ClientApp).sdkInitStatus.first()) {
                // if this is success
                is NGWrappedResult.Success -> {
                    Log.d(TAG, "MainActivity awaited init success: $initStatus")

                    // then do a setup call for downloading the param and keys
                    val setupStatus = NGHeadlessSetup.initialSetup(this@MainActivity)
                    Log.d(TAG, "MainActivity setup status: $setupStatus")

                    // lastly we can launch the sale
                    launchSale()
                }

                else -> {
                    Log.d(TAG, "MainActivity awaited init failed! $initStatus")
                }
            }
        }
    }

    fun launchSale() = launcher.launch(
        NGPoiRequest.ActionNew(
            tranType = TranType.SALE,
            amount = Amount(
                BigDecimal("1.0"),
                Currency.getInstance("HKD"),
            ),
            profileId = "prof_01HYYPGVE7VB901M40SVPHTQ0V",
        )
    )
}
```

--------------------------------

### Quick Usage: Start Payment in Flutter

Source: https://docs.neurogine.com/n2Tap/getting-started/intro

Example demonstrating how to initiate a payment using the n2Tap SDK in a Flutter application. It shows how to import the SDK and call the startPayment function with amount and currency.

```dart
import 'package:flutter/material.dart';
import 'package:n2tap_flutter/n2tap_flutter.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
	@override
	Widget build(BuildContext context) {
		return MaterialApp(
			home: Scaffold(
				body: Center(
					child: ElevatedButton(
						onPressed: () async {
							final result = await N2Tap.startPayment(amount: 1000, currency: 'USD');
							print(result);
						},
						child: Text('Pay'),
					),
				),
			),
		);
	}
}
```

--------------------------------

### Perform Initial SDK Setup in MainActivity

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Initiates the initial setup for the SDK, which includes downloading EMV parameters, terminal configurations, and necessary keys. This is a suspending function and should be called once per application lifecycle, typically from an Activity's lifecycle scope.

```kotlin
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import com.neurogine.softpos.sdk.headless.NGHeadlessSetup
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity() {
    // ... other activity code ...

    fun setup() = lifecycleScope.launch {
        val setupResp = NGHeadlessSetup.initialSetup(this@MainActivity)
        Log.d(TAG, "setup: $setupResp")
    }

    companion object {
        private const val TAG = "MainActivity"
    }
}
```

--------------------------------

### Quick Usage: Start Payment in React Native

Source: https://docs.neurogine.com/n2Tap/getting-started/intro

Example demonstrating how to initiate a payment using the n2Tap SDK in a React Native application. It shows how to import the SDK and call the startPayment function with amount and currency.

```javascript
import React from 'react'
import { SafeAreaView, Button } from 'react-native'
import N2Tap from '@neurogine/n2tap-react-native'

export default function App() {
	const startPayment = async () => {
		const result = await N2Tap.startPayment({ amount: 1000, currency: 'USD' })
		console.log('payment result', result)
	}

	return (
		<SafeAreaView>
			<Button title="Pay" onPress={startPayment} />
		</SafeAreaView>
	)
}
```

--------------------------------

### Perform Initial SoftPOS Setup with NGHeadlessSetup

Source: https://docs.neurogine.com/suite-sdk/api-reference/headless-setup

Performs the initial setup for the SoftPOS using the `initialSetup` method. This suspended method should be called once per app installation and can accept an optional builder to configure setup options, such as enabling test CAPKs. It returns a `SetupResp` object detailing the setup results.

```kotlin
// with default option
val setupResult1 = NGHeadlessSetup.initialSetup(context)

// with test capk
val setupResult2 = NGHeadlessSetup.initialSetup(context) {
  withTestCapk = true
}
```

--------------------------------

### Install n2Tap Flutter SDK

Source: https://docs.neurogine.com/n2Tap/getting-started/intro

Instructions for installing the n2Tap Flutter SDK using pub. This package provides native modules for integrating payments into Flutter applications.

```bash
flutter pub add n2tap_flutter
```

--------------------------------

### Launch a Sale Transaction Request

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Launches a new sale transaction request using the registered launcher. It requires mandatory parameters like transaction type, amount, and profile ID.

```kotlin
fun launchSale() = launcher.launch(
    NGPoiRequest.ActionNew(
        tranType = TranType.SALE,
        amount = Amount(
            BigDecimal("1.0"),
            Currency.getInstance("HKD"),
        ),
        profileId = "prof_01HYYPGVE7VB901M40SVPHTQ0V",
    )
)
```

--------------------------------

### Quick Start: N2App Payment Integration (Flutter)

Source: https://docs.neurogine.com/n2Tap/flutter/guides

A minimal Flutter example demonstrating how to use the n2app plugin. It includes checking if the SoftPOS app is installed and triggering a sale transaction with success and failure callbacks.

```dart
import 'package:flutter/material.dart';
import 'package:n2app/n2app.dart';
import 'dart:math';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: PaymentScreen(),
    );
  }
}

class PaymentScreen extends StatefulWidget {
  @override
  _PaymentScreenState createState() => _PaymentScreenState();
}

class _PaymentScreenState extends State<PaymentScreen> {
  bool? _isSoftPosInstalled;

  @override
  void initState() {
    super.initState();
    _checkSoftPosInstallation();
  }

  Future<void> _checkSoftPosInstallation() async {
    final installed = await N2app.checkAppInstalled();
    setState(() {
      _isSoftPosInstalled = installed;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('N2App Payment')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              _isSoftPosInstalled == true
                  ? 'SoftPOS is installed ✓'
                  : 'SoftPOS not installed ✗',
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: _processSaleTransaction,
              child: Text('Process Payment'),
            ),
          ],
        ),
      ),
    );
  }

  void _processSaleTransaction() {
    N2app.triggerSaleTransaction(
      amount: 10.50,
      posMessageId: '${Random().nextInt(100000)}',
      onSuccess: (result) {
        print('Transaction successful: ${result.message}');
        // Handle success
      },
      onFailed: (error) {
        print('Transaction failed: $error');
        // Handle failure
      },
    );
  }
}
```

--------------------------------

### Install n2Tap React Native SDK

Source: https://docs.neurogine.com/n2Tap/getting-started/intro

Instructions for installing the n2Tap React Native SDK using npm or yarn. This package provides native modules for integrating payments into React Native applications.

```bash
# yarn
yarn add @neurogine/n2tap-react-native

# or npm
npm install @neurogine/n2tap-react-native
```

--------------------------------

### Configure Neurogine Registry in Gradle Properties

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Sets up the Neurogine client registry credentials in the `gradle.properties` file. This includes login and token values required to access the Neurogine package repository. Ensure these are set in your global `~/.gradle/gradle.properties` and not committed to version control.

```properties
# neurogine client registry
NEUROGINE_REGISTRY_LOGIN=neurogine-product-support
NEUROGINE_REGISTRY_TOKEN={token-value}
```

--------------------------------

### Register Custom Application Class in AndroidManifest.xml

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Specifies the custom application class (ClientApp) in the AndroidManifest.xml file. This ensures that the `onCreate` method of `ClientApp` is called when the application starts, allowing for SDK initialization.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.MyApplication"
        android:name=".ClientApp"
        tools:targetApi="31">
        <!-- other activities -->
    </application>
</manifest>
```

--------------------------------

### Extend NGHeadlessActivity for Customization

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Shows the basic structure for extending the `NGHeadlessActivity` class. This is the starting point for implementing custom UI logic within the Neurogine SDK.

```kotlin
class CustomHeadlessImpl : NGHeadlessActivity()
```

--------------------------------

### Create Headless Activity in Kotlin

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Defines a custom headless activity by inheriting from NGHeadlessActivity. This is the first step in setting up a headless integration. Ensure this activity is declared in your AndroidManifest.xml.

```kotlin
import com.neurogine.softpos.sdk.headless.NGHeadlessActivity

class ClientHeadlessImpl: NGHeadlessActivity()
```

--------------------------------

### Install react-native-n2app Plugin

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Installs the react-native-n2app plugin from a local .tgz file. This is applicable for both standard React Native and Expo managed workflows. Ensure the .tgz file is placed in the project root before running the command.

```bash
npm install ./react-native-n2app-0.1.0.tgz
yarn add ./react-native-n2app-0.1.0.tgz
```

--------------------------------

### Add Neurogine Registry to Project Settings Gradle

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Configures the project's `settings.gradle.kts` to include the Neurogine Maven registry. It retrieves credentials from `gradle.properties` and specifies the registry URL. This allows Gradle to fetch dependencies from the Neurogine repository.

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Neurogine maven registry
        maven {
            val NEUROGINE_REGISTRY_LOGIN: String? by settings
            val NEUROGINE_REGISTRY_TOKEN: String? by settings

            requireNotNull(NEUROGINE_REGISTRY_LOGIN) {
                """
                    Please set your Neurogine Github credential in `gradle.properties`.
                    On local machine,
                    ** DO NOT **
                    ** DO NOT **
                    ** DO NOT **
                    Do not put it in the project's file. (and accidentally commit and push)
                    ** DO **
                    Do set it in your machine's global (~/.gradle/gradle.properties)
                """.trimIndent()
            }
            requireNotNull(NEUROGINE_REGISTRY_TOKEN)
            println("Neurogine GPR: $NEUROGINE_REGISTRY_LOGIN")

            name = "NeurogineMavenClientRegistry"
            url = uri("<your-neurogine-maven-registry-url>")
            credentials {
                username = NEUROGINE_REGISTRY_LOGIN
                password = NEUROGINE_REGISTRY_TOKEN
            }
        }
    }
}
```

--------------------------------

### Initialize Neurogine SDK in Android Application

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Initializes the Neurogine SDK upon application startup by calling `NGHeadlessSetup.initSoftPos`. This is a suspend function that requires the application context and a license file. The initialization status is emitted via a SharedFlow.

```kotlin
import android.app.Application
import android.util.Log
import com.neurogine.softpos.sdk.headless.NGHeadlessSetup
import com.neurogine.softpos.sdk.headless.SdkInitResp
import com.neurogine.softpos.sdk.headless.NGWrappedResult
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.launch

class ClientApp : Application() {
    private val appScope = CoroutineScope(Dispatchers.Main)
    private val _sdkInitStatus = MutableSharedFlow<NGWrappedResult<SdkInitResp>>(replay = 1)
    val sdkInitStatus: SharedFlow<NGWrappedResult<SdkInitResp>> = _sdkInitStatus

    override fun onCreate() {
        super.onCreate()
        appScope.launch {
            val clientAppInitRes = NGHeadlessSetup.initSoftPos(this@ClientApp, "your.license")
            Log.d(TAG, "Application init: $clientAppInitRes")
            _sdkInitStatus.emit(clientAppInitRes)
        }
    }

    companion object {
        private const val TAG = "ClientApp"
    }
}
```

--------------------------------

### Register Headless Activity in AndroidManifest.xml

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Declares the custom headless activity (ClientHeadlessImpl) in the application's AndroidManifest.xml file. This makes the activity available to the Android system.

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.MyApplication"
        tools:targetApi="31">
        ...

        <activity
            android:name=".ClientHeadlessImpl"
            android:launchMode="singleTask"
            />
    </application>
</manifest>
```

--------------------------------

### Create Await Card Animation with TextureView

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Shows how to create an await card animation using a `TextureView` and playing a video from the `/res/raw` directory. It sets up a `MediaPlayer` and handles the `SurfaceTextureListener` to play the video.

```kotlin
//..
override fun createAwaitCardIndicatorView(context: Context): View {
    val mediaPlayer = MediaPlayer()
    return TextureView(context).apply {
        surfaceTextureListener = object : TextureView.SurfaceTextureListener {
            override fun onSurfaceTextureAvailable(surface: SurfaceTexture, width: Int, height: Int) {
                val videoUri = Uri.Builder()
                    .scheme(ContentResolver.SCHEME_ANDROID_RESOURCE)
                    .authority(context.packageName)
                    .appendPath("${R.raw.demo_await}")
                    .build()

                mediaPlayer.apply {
                    setDataSource(context, videoUri)
                    setSurface(Surface(surface))
                    isLooping = true
                    prepareAsync()
                    setOnPreparedListener { start() }
                }
            }

            override fun onSurfaceTextureSizeChanged(surface: SurfaceTexture, width: Int, height: Int) {}
            override fun onSurfaceTextureDestroyed(surface: SurfaceTexture): Boolean = true
            override fun onSurfaceTextureUpdated(surface: SurfaceTexture) {}
        }
    }
}
```

--------------------------------

### Inflate XML Layout with Data Binding

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Demonstrates how to inflate an XML layout using `DataBindingUtil` and apply data binding. It shows the creation of a `CompAmountDisplayBinding` object and binding data to its variables.

```kotlin
private class CustomViewProvider :
    AmountView
    //...
{
    // amount component with view inflated from xml layout
    override fun createAmountView(context: Context, amount: Amount, description: String?): View {
        val inflater = LayoutInflater.from(context)
        // note the `CompAmountDisplayBinding` is auto generated as the xml layout is wrapped with the `<layout>` tag
        return DataBindingUtil.inflate<CompAmountDisplayBinding>(inflater, R.layout.comp_amount_display, null, false)
            .apply {
                root.layoutParams = ConstraintLayout.LayoutParams(
                    ConstraintLayout.LayoutParams.MATCH_PARENT,
                    ConstraintLayout.LayoutParams.MATCH_PARENT
                )
                // bind the amount and description to the XML's corresponding `data.variable` tag
                this.amount = amount.value.toString()
                this.description = "dummy description"
            }
            .root
    }
}
```

--------------------------------

### Register Activity Result Launcher for Transactions

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Registers an activity result launcher to handle the callback from NGHeadlessActivity for transaction results. It logs the received NGWrappedResult<Transaction>.

```kotlin
private val launcher = registerForActivityResult(
    NGHeadlessActivity.contract(ClientHeadlessImpl::class.java)
) {
    Log.d(TAG, "MainActivity launcher result back for NGWrappedResult<Transaction>: $it}")
}
```

--------------------------------

### Define Custom ViewProvider for UI Components

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Creates a custom ViewProvider class that implements the necessary SDK interfaces for UI components. This class will be responsible for providing the custom views.

```kotlin
import com.neurogine.softpos.sdk.headless.ui.*

private class CustomViewProvider :
    AmountView,
    ProgressIndicatorView,
    AwaitCardIndicatorView,
    AcceptanceMarksView,
    SignatureScreenView
```

--------------------------------

### Create AmountView Programmatically

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Demonstrates how to programmatically create a custom `AmountView` by inflating a LinearLayout and adding TextViews for displaying the amount and description. This method allows for direct UI construction within the SDK.

```kotlin
private class CustomViewProvider :
    AmountView
    //...
{
    // amount component with view created programmatically
    override fun createAmountView(context: Context, amount: Amount, description: String?) =
        // create the linear layout with the context passed in
        LinearLayout(context).apply {
            orientation = LinearLayout.VERTICAL
            layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT)
            // create and add 2 textview for the label and the amount value display
            addView(TextView(context).apply {
                textSize = 30F
                textAlignment = TEXT_ALIGNMENT_CENTER
                text = "Total amount here"
            })
            addView(TextView(context).apply {
                textSize = 40F
                textAlignment = TEXT_ALIGNMENT_CENTER
                text = "${amount.currency.currencyCode}${amount.value}"
            })
        }
}
```

--------------------------------

### Customize Neurogine SDK UI with Jetpack Compose

Source: https://docs.neurogine.com/suite-sdk/customization-guide/compose

This code example demonstrates how to customize various UI components of the Neurogine Headless SDK using Jetpack Compose. It involves creating a custom `NGHeadlessActivity` and overriding the `provideUi` method to return a custom `UiProvider`. The `UiProvider` then overrides specific composable functions to apply custom styling, such as adding a red border to the default components.

```kotlin
class ClientHeadlessImpl : NGHeadlessActivity() {
  override fun provideUi(): UiProvider = ClientUiProvider
}
 
object ClientUiProvider : UiProvider() {
  @Composable
  override fun AmountDisplay(amount: Amount, description: String?) {
    Box(
      modifier = Modifier.border(1.dp, Color.Red),
      contentAlignment = Alignment.Center
    ) {
      super.AmountDisplay(amount, description)
    }
  }
 
  @Composable
  override fun AcceptanceMarkDisplay(supportedPayments: List<PaymentMethod>, showWallet: Boolean) {
    Box(
      modifier = Modifier.border(1.dp, Color.Red),
      contentAlignment = Alignment.Center
    ) {
      super.AcceptanceMarkDisplay(supportedPayments, true)
    }
  }
 
  @Composable
  override fun AwaitCardIndicator() {
    Box(
      modifier = Modifier
        .fillMaxSize()
        .border(1.dp, Color.Red),
    ) {
      super.AwaitCardIndicator()
    }
  }
 
  @Composable
  override fun ProgressIndicator() {
    Box(
      modifier = Modifier.border(1.dp, Color.Red),
      contentAlignment = Alignment.Center
    ) {
      super.ProgressIndicator()
    }
  }
 
  @Composable
  override fun UiStateDisplay(modifier: Modifier, uiState: UiState, countdownSec: Int) {
    Box(
      modifier = Modifier.border(1.dp, Color.Red),
      contentAlignment = Alignment.Center
    ) {
      super.UiStateDisplay(modifier, uiState, countdownSec)
    }
  }
}
```

--------------------------------

### Component View Interfaces for Customization

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Lists the interfaces provided by the SDK that allow developers to customize specific UI components. By extending these interfaces, developers can provide their own implementations for how these components are displayed.

```kotlin
interface AmountView {
    fun createAmountView(context: Context, amount: Amount, description: String? = null): View
}

interface AwaitCardIndicatorView {
    fun createAwaitCardIndicatorView(context: Context): View
}

interface AcceptanceMarksView {
    fun createAcceptanceMarksView(context: Context, supportedPayments: List<PaymentMethod>, showWallet: Boolean = true): View
}

interface ProgressIndicatorView {
    fun createProgressIndicatorView(context: Context): View
}
```

--------------------------------

### Configure Packaging Options for Resource Exclusion

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Ensures specific resource files are excluded from the final Android package to avoid conflicts. This configuration is added to the `android.packagingOptions` block in the app's `build.gradle.kts`. It's a standard practice for managing library resources.

```kotlin
android {
    // ...
    packagingOptions {
        resources {
            excludes += "/META-INF/{AL2.0,LGPL2.1}"
            excludes += "/META-INF/DEPENDENCIES"
            excludes += "/META-INF/LICENSE"
            excludes += "/META-INF/LICENSE.txt"
            excludes += "/META-INF/license.txt"
            excludes += "/META-INF/NOTICE"
            excludes += "/META-INF/NOTICE.txt"
            excludes += "/META-INF/notice.txt"
            excludes += "/META-INF/ASL2.0"
            excludes += "/META-INF/*.kotlin_module"
        }
    }
}
```

--------------------------------

### Install Flutter Dependencies

Source: https://docs.neurogine.com/n2Tap/flutter/guides

Command to run after updating your pubspec.yaml file to download and install the project's dependencies, including the n2app plugin.

```bash
flutter pub get
```

--------------------------------

### Install Local React Native n2app Package

Source: https://docs.neurogine.com/n2Tap/react-native/faq

These npm commands demonstrate how to install the n2Tap React Native plugin from a local .tgz file. The correct path to the file is essential, whether it's in the project root or a subdirectory.

```bash
npm install ./react-native-n2app-0.1.0.tgz
```

```bash
npm install ./path/to/react-native-n2app-0.1.0.tgz
```

--------------------------------

### Expo Prebuild for Native Dependencies

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Prebuilds the Expo project to generate native folders, which is a necessary step after installing native dependencies like the react-native-n2app plugin in a managed Expo workflow. The --clean flag ensures a fresh build.

```bash
npx expo prebuild --clean
```

--------------------------------

### Implement Custom Headless Activity with ViewProvider

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Extends the base NGHeadlessActivity and provides a custom ViewProvider to integrate custom UI components. This involves creating a class that implements various View interfaces and wiring it up using UiProvider.

```kotlin
class CustomHeadlessImpl : NGHeadlessActivity() {
    override fun provideUi() = CustomViewProvider().run {
        UiProvider(
            amountView = this,
            progressIndicatorView = this,
            awaitCardIndicatorView = this,
            acceptanceMarksView = this
        )
    }
}
```

--------------------------------

### Check if Neurogine SoftPOS App is Installed

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Asynchronously checks if the Neurogine SoftPOS application is installed on the device. It logs whether the app is installed or not, and includes basic error handling. This function is crucial for ensuring the SoftPOS app is available before attempting other operations.

```typescript
const checkSoftPos = async () => {
   try {
      const isInstalled = await N2app.isSoftPosInstalled();
      if (isInstalled) {
         console.log('SoftPOS app is installed');
      } else {
         console.log('SoftPOS app is not installed');
         // Optionally prompt user to install
      }
   } catch (error) {
      console.error('Error checking SoftPOS:', error);
   }
};
```

--------------------------------

### Configure AndroidManifest.xml for n2Tap Plugin

Source: https://docs.neurogine.com/n2Tap/react-native/examples

This example demonstrates a complete AndroidManifest.xml configuration for the n2Tap React Native plugin. It includes necessary permissions, the 'queries' section for Android 11+ package visibility, and 'meta-data' for SoftPOS package configuration. Ensure the package name in 'queries' and 'meta-data' matches your SoftPOS app.

```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <!-- Permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
 
    <!-- Queries for Android 11+ package visibility -->
    <queries>
        <intent>
            <action android:name="android.intent.action.PROCESS_TEXT"/>
            <data android:mimeType="text/plain"/>
        </intent>
        <!-- Use the package name that matches your environment -->
        <package android:name="com.neurogine.softpos.stage" />
    </queries>
 
    <application
      android:name=".MainApplication"
      android:label="@string/app_name"
      android:icon="@mipmap/ic_launcher"
      android:roundIcon="@mipmap/ic_launcher_round"
      android:allowBackup="false"
      android:theme="@style/AppTheme"
      android:supportsRtl="true">
 
      <!-- SoftPOS Package Configuration -->
      <!-- This value is read dynamically by the N2app module -->
      <meta-data
          android:name="softposName"
          android:value="com.neurogine.softpos.stage" />
 
      <activity
        android:name=".MainActivity"
        android:label="@string/app_name"
        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
        android:launchMode="singleTask"
        android:windowSoftInputMode="adjustResize"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
      </activity>
    </application>
</manifest>
```

--------------------------------

### Check SoftPOS Installation Early (Flutter)

Source: https://docs.neurogine.com/n2Tap/flutter/best-practices

Verifies if the SoftPOS application is installed before initiating payment transactions. This prevents errors by ensuring the necessary application is available. It returns a boolean indicating installation status.

```dart
Future<void> initializePayments() async {
    final isInstalled = await N2app.checkAppInstalled();
 
    if (isInstalled != true) {
        // Direct user to install SoftPOS
        _showInstallPrompt();
        return;
    }
 
    // Continue with Initialization
    await warmUp();
}
```

--------------------------------

### Add Neurogine Embedded Payment SDK Dependency

Source: https://docs.neurogine.com/suite-sdk/getting-started/quickstart

Adds the Neurogine Embedded Payment SDK dependency to the app's `build.gradle.kts` file. It specifies both the release (`headless`) and debug (`headless-stage`) versions of the SDK. The `headless` version connects to the production environment, while `headless-stage` is for development and debugging.

```kotlin
dependencies {
    // ... other deps

    // ++
    releaseImplementation("com.neurogine.softpos.sdk:headless:1.0.0")
    // ++ for debug SDK, you can declare as debugImplementation
    debugImplementation("com.neurogine.softpos.sdk:headless-stage:1.0.0")
}
```

--------------------------------

### Initialize N2App SDK and Check Status - Dart

Source: https://docs.neurogine.com/n2Tap/flutter/examples

Initializes the N2App SDK by retrieving the platform version and checking if the SoftPOS application is installed. It also includes a warm-up call if the app is installed. This function is crucial for setting up the payment environment.

```dart
import 'dart:async';
import 'dart:math';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:n2app/n2app.dart';

void main() {
  runApp(MaterialApp(home: const MyApp()));
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _platformVersion = 'Unknown';
  bool? _appInstalled = false;
  bool _isActivated = false;

  @override
  void initState() {
    super.initState();
    initPlatformState();
  }

  Future<void> initPlatformState() async {
    String platformVersion;
    bool? isAppInstalled;
    
    try {
      platformVersion = await N2app.getPlatformVersion() ?? 'Unknown';
      isAppInstalled = await N2app.checkAppInstalled();
      
      // Warm up if installed
      if (isAppInstalled == true) {
        N2app.warmUp(
          onSuccess: (message) => print('Warm up success'),
          onFailed: (message) => print('Warm up failed'),
        );
      }
    } on PlatformException {
      platformVersion = 'Failed to get platform version.';
    }

    if (!mounted) return;

    setState(() {
      _appInstalled = isAppInstalled;
      _platformVersion = platformVersion;
    });
  }

  // ... other methods ...

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('N2App Payment Demo'),
        backgroundColor: Colors.blue,
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(20),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(16),
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.start,
                  children: [
                    Text(
                      'System Status',
                      style: Theme.of(context).textTheme.titleLarge,
                    ),
                    const SizedBox(height: 10),
                    Text('Platform: $_platformVersion'),
                    Text('SoftPOS Installed: ${_appInstalled == true ? "✓" : "✗"}'),
                    Text('Activated: ${_isActivated ? "✓" : "✗"}'),
                  ],
                ),
              ),
            ),
            // ... other widgets ...
          ],
        ),
      ),
    );
  }
}
```

--------------------------------

### Enable and Configure ScreenProvider in Custom Activity

Source: https://docs.neurogine.com/suite-sdk/customization-guide/compose-screen

Overrides the experimentalScreenProvider flag to true and provides a custom ScreenProvider instance within a custom NGHeadlessActivity. This enables custom screen handling.

```kotlin
class HeadlessImplWithScreenProvider : NGHeadlessActivity() {
    override val experimentalScreenProvider = true
    override val screenProvider = object : ScreenProvider() {}
}
```

--------------------------------

### Enable Data Binding in Gradle Kotlin DSL

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

Enables the data binding feature in your Android project by adding the configuration to your `build.gradle.kts` file. This allows for automatic generation of binding classes from XML layouts.

```kotlin
android {
    ..
    dataBinding {
        enable = true
    }
}
```

--------------------------------

### Handling Success and Failure Example

Source: https://docs.neurogine.com/suite-sdk/api-reference/wrapped-result

Demonstrates how to handle both successful and failed results using the `NGWrappedResult` class.

```APIDOC
## Examples

### Handling Success and Failure

```kotlin
val result: NGWrappedResult<SomeData> = performOperation()

when (result) {
  is NGWrappedResult.Success -> {
    val data = result.value
    // Handle success
  }
  is NGWrappedResult.Failure -> {
    val errorCode = result.code
    val errorMessage = result.message
    // Handle failure
  }
}
```
```

--------------------------------

### Create Custom NGHeadlessActivity

Source: https://docs.neurogine.com/suite-sdk/customization-guide/compose-screen

Defines a custom implementation of NGHeadlessActivity. This is the first step in customizing the SDK's behavior and UI.

```kotlin
class HeadlessImplWithScreenProvider : NGHeadlessActivity()
```

--------------------------------

### Customize Acceptance Marks View with Payment Methods and Wallets (Kotlin)

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

This snippet shows how to create a custom view for displaying acceptance marks. It iterates through a list of supported payment methods and adds their corresponding images to a LinearLayout. It also includes logic to display a wallet icon if specified. Dependencies include the Neurogine SDK's `getImageRes()` extension.

```kotlin
import android.content.Context
import android.view.View
import android.widget.ImageView
import android.widget.LinearLayout
import com.neurogine.softpos.sdk.headless.ui.component.resource.getImageRes
import com.neurogine.softpos.sdk.headless.model.payment.PaymentMethod
import com.neurogine.softpos.sdk.headless.model.wallet.WalletType

// Extension function to convert DP to pixels (assuming it's defined elsewhere)
fun Int.intToDp(context: Context): Int {
    return (this * context.resources.displayMetrics.density).toInt()
}

//..
override fun createAcceptanceMarksView(context: Context, supportedPayments: List<PaymentMethod>, showWallet: Boolean): View {
    return LinearLayout(context).apply {
        orientation = LinearLayout.HORIZONTAL

        val iconLp = LinearLayout.LayoutParams(
            LinearLayout.LayoutParams.WRAP_CONTENT,
            LinearLayout.LayoutParams.WRAP_CONTENT,
        ).apply {
            marginEnd = 16.intToDp(context)
        }

        supportedPayments.forEach { pm ->
            addView(ImageView(context).apply {
                setImageResource(pm.getImageRes()).apply {
                    layoutParams = iconLp
                }
            })
        }
        if (showWallet) {
            addView(ImageView(context).apply {
                setImageResource(WalletType.APPLE_PAY.getImageRes())
            })
        }
    }
}
```

--------------------------------

### Customize Awaiting Card Screen with Jetpack Compose

Source: https://docs.neurogine.com/suite-sdk/customization-guide/compose-screen

Provides a custom Composable function for the AwaitingCardScreen. This function overrides the default screen to display custom UI elements and information, such as title, description, countdown, amount, and supported payment methods.

```kotlin
@Composable
override fun AwaitingCardScreen(
    poiRequest: NGPoiRequest.ActionNew,
    awaitingFlow: Flow<UiState.Awaiting>,
    supportedMethods: List<PaymentMethod>,
    countdownFlow: StateFlow<Int>,
    onAbort: () -> Unit
) {
    val countdownSec by countdownFlow.collectAsStateWithLifecycle()
    val uiState by awaitingFlow.collectAsStateWithLifecycle(UiState.Preparing.Idle)
    Shell {
        Title(text = "Await Card Screen")
        Desc(text = "-> awaiting card tapping")
        Text(text = "countdown: $countdownSec")
        Text(text = "uiState: $uiState")
        AmountText(poiRequest.amount)
        NGPoiRequestText(poiRequest)
        Text(text = "supportedMethods: $supportedMethods")
        FlowRow(
            modifier = Modifier.fillMaxWidth(),
            verticalArrangement = Arrangement.spacedBy(HeadlessTheme.spacing.xs2),
            horizontalArrangement = Arrangement.spacedBy(
                HeadlessTheme.spacing.xs,
                Alignment.CenterHorizontally
            )
        ) {
            supportedMethods.forEach { it.Icon() }
        }
        Button(onClick = onAbort) {
            Text(text = "Abort")
        }
    }
}
```

--------------------------------

### Create Circular Progress Indicator View (Kotlin)

Source: https://docs.neurogine.com/suite-sdk/customization-guide/xml

This Kotlin code demonstrates how to create and configure a `CircularProgressIndicator` from the Material Components library. It sets the indicator size, track thickness, color, and makes it indeterminate and visible. An alternative commented-out section shows how to use a custom video animation as a progress indicator.

```kotlin
import android.content.Context
import android.graphics.Color
import android.view.View
import com.google.android.material.progressindicator.CircularProgressIndicator
import android.view.ViewGroup

// Extension function to convert DP to pixels (assuming it's defined elsewhere)
fun Int.intToDp(context: Context): Int {
    return (this * context.resources.displayMetrics.density).toInt()
}

//..
override fun createProgressIndicatorView(context: Context): View {
    // the circular progress from material library
    return CircularProgressIndicator(context).apply {
        layoutParams = ViewGroup.LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT,
            ViewGroup.LayoutParams.MATCH_PARENT
        )
        indicatorSize = 200.intToDp(context)
        trackThickness = 8.intToDp(context)
        isIndeterminate = true
        trackColor = Color.TRANSPARENT
        setIndicatorColor(Color.parseColor("#FFD503"))
        isVisible = true
    }
    // or you can also use a custom animation mp4 from the res/ raw
    //val mediaPlayer = MediaPlayer()
    //return TextureView(context).apply {
    //    surfaceTextureListener = object : TextureView.SurfaceTextureListener {
    //        override fun onSurfaceTextureAvailable(surface: SurfaceTexture, width: Int, height: Int) {
    //            val videoUri = Uri.Builder()
    //                .scheme(ContentResolver.SCHEME_ANDROID_RESOURCE)
    //                .authority(context.packageName)
    //                .appendPath("${R.raw.demo_processing}")
    //                .build()
    //            mediaPlayer.apply {
    //                setDataSource(context, videoUri)
    //                setSurface(Surface(surface))
    //                isLooping = true
    //                prepareAsync()
    //                setOnPreparedListener { start() }
    //            }
    //        }
    //        override fun onSurfaceTextureSizeChanged(surface: SurfaceTexture, width: Int, height: Int) {}
    //        override fun onSurfaceTextureDestroyed(surface: SurfaceTexture): Boolean = true
    //        override fun onSurfaceTextureUpdated(surface: SurfaceTexture) {}
    //    }
    //}
}
```

--------------------------------

### Process Refund Transaction with N2app

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Initiates a refund for a previous transaction. Requires the original transaction ID, a passcode, and a POS message ID. Reports success or failure of the refund process.

```typescript
const processRefund = async (
  originalTransactionId: string,
  passcode: string,
  posMessageId: string
) => {
  try {
    const response: N2AppResponse = await N2app.startRefund(
      originalTransactionId,
      passcode,
      posMessageId
    );
 
    if (response.rspCode === '00') {
      console.log('Refund successful!');
      console.log('Transaction ID:', response.tranId);
      console.log('Transaction Status:', response.tranStatus);
    } else {
      console.log('Refund failed:', response.rspMsg);
    }
  } catch (error) {
    console.error('Refund error:', error);
  }
};

// Example: Process a refund
const messageId = `POS-${Date.now()}`;
processRefund('TXN123456789', 'ADMIN_PASSWORD', messageId);
```

--------------------------------

### Warm Up n2TapPlugin on App Start (Flutter)

Source: https://docs.neurogine.com/n2Tap/flutter/best-practices

Calls the `warmUp()` method early in the application's lifecycle to reduce subsequent transaction latency. This prepares the plugin for faster transactions. It includes success and failure callbacks for logging.

```dart
@override
void initState() {
    super.initState();
    _initializeN2app();
}
 
Future<void> _initializeN2app() async {
    final installed = await N2app.checkAppInstalled();
    if (installed == true) {
        N2app.warmUp(
            onSuccess: (_) => print('Ready for transactions'),
            onFailed: (_) => print('Warm up failed'),
        );
    }
}
```

--------------------------------

### Top-level build.gradle.kts Configuration for Android

Source: https://docs.neurogine.com/suite-sdk/getting-started/setup-requirement

This snippet shows the top-level build.gradle.kts file configuration for an Android project. It includes essential plugins like the Android Application plugin and the Kotlin Android plugin, specifying their versions.

```kotlin
// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
  id("com.android.application") version "8.1.1" apply false
  kotlin("android") version "1.9.0" apply false
}
```

--------------------------------

### Complete Authorization Transaction with N2app

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Completes a previously initiated authorization transaction. Requires the original transaction ID, amount, and a POS message ID. Logs the outcome of the completion attempt.

```typescript
const completeAuth = async (
  originalTransactionId: string,
  amount: number,
  posMessageId: string
) => {
  try {
    const response: N2AppResponse = await N2app.startAuthCompletion(
      originalTransactionId,
      amount,
      posMessageId
    );
 
    if (response.rspCode === '00') {
      console.log('Authorization completion successful!');
      console.log('Transaction ID:', response.tranId);
      console.log('Transaction Status:', response.tranStatus);
    } else {
      console.log('Authorization completion failed:', response.rspMsg);
    }
  } catch (error) {
    console.error('Authorization completion error:', error);
  }
};

// Example: Complete an authorization
const messageId = `POS-${Date.now()}`;
completeAuth('TXN123456789', 50.0, messageId);
```

--------------------------------

### App-level build.gradle.kts Configuration for Android

Source: https://docs.neurogine.com/suite-sdk/getting-started/setup-requirement

This snippet details the app-level build.gradle.kts file for an Android project. It configures the application ID, SDK versions, build types, compilation options, packaging options, and includes Neurogine SDK dependencies.

```kotlin
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}
 
android {
    namespace = "com.neurogine.example.myapplication"
    compileSdk = 34
 
    defaultConfig {
        applicationId = "com.neurogine.example.myapplication"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"
 
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
 
    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }
    packagingOptions {
        resources {
            excludes += "/META-INF/{AL2.0,LGPL2.1}"
            excludes += "/META-INF/DEPENDENCIES"
            excludes += "/META-INF/LICENSE"
            excludes += "/META-INF/LICENSE.txt"
            excludes += "/META-INF/license.txt"
            excludes += "/META-INF/NOTICE"
            excludes += "/META-INF/NOTICE.txt"
            excludes += "/META-INF/notice.txt"
            excludes += "/META-INF/ASL2.0"
            excludes += "/META-INF/*.kotlin_module"
        }
    }
}
 
dependencies {
    //... other deps
 
    // Neurogine
    debugImplementation("com.neurogine.softpos.sdk:headless-stage:1.0.0")
    releaseImplementation("com.neurogine.softpos.sdk:headless:1.0.0")
}
```

--------------------------------

### Process Authorization Transaction with N2app

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Initiates an authorization transaction. Requires the transaction amount and a unique POS message ID. Handles success and failure responses, logging transaction details upon success.

```typescript
const processAuth = async (amount: number, posMessageId: string) => {
  try {
    const response: N2AppResponse = await N2app.startAuth(amount, posMessageId);
 
    if (response.rspCode === '00') {
      console.log('Authorization successful!');
      console.log('Transaction ID:', response.tranId);
      console.log('Transaction Status:', response.tranStatus);
      console.log('Approval Code:', response.approvalCode);
      console.log('Total Amount:', response.totalAmount);
    } else {
      console.log('Authorization failed:', response.rspMsg);
    }
  } catch (error) {
    console.error('Authorization error:', error);
  }
};

// Example: Process authorization for 50.00
const messageId = `POS-${Date.now()}`;
processAuth(50.0, messageId);
```

--------------------------------

### Warm Up Neurogine SoftPOS Application

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Initiates a warm-up sequence for the Neurogine SoftPOS application. It returns a response object indicating success or failure, along with a message. This is often a prerequisite for subsequent operations like activation or transactions.

```typescript
const warmUpSoftPos = async () => {
   try {
      const response: N2AppResponse = await N2app.warmUp();
      if (response.rspCode === '00') {
         console.log('SoftPOS warmed up successfully');
      } else {
         console.log('Warm up failed:', response.rspMsg);
      }
   } catch (error) {
      console.error ('Error warming up SoftPOS:', error);
   }
};
```

--------------------------------

### Process a Sale Transaction with SoftPOS

Source: https://docs.neurogine.com/n2Tap/react-native/guides

Initiates a sales transaction using the Neurogine SoftPOS application. It requires the transaction amount and a unique message ID. Upon completion, it logs the transaction status, ID, and detailed data including card information if available. Handles both successful and failed transaction scenarios.

```typescript
const processSale = async (amount: number, posMessageId: string) => {
   try {
      const response: N2AppResponse = await N2app.startSale(amount, posMessageId);

      if (response.rspCode === '00') {
      console.log('Sale successful!');
      console.log('Transaction ID:', response.tranId);
      console.log('Response Type:', response.type);

      // Access detailed transaction data
      if (response.data) {
        const txnData = response.data as TransactionResponse;
        console.log('Transaction Status:', txnData.tranStatus);
        console.log('Approval Code:', txnData.approvalCode);
        console.log('Total Amount:', txnData.totalAmount);
        console.log('Masked Account:', txnData.maskedAccount);
        console.log('Payment Method:', txnData.paymentMethod);
        console.log('Entry Mode:', txnData.entryMode);
        console.log('RRN:', txnData.rrn);
        console.log('Trace:', txnData.trace);

        // Access card data if available
        if (txnData.cardData) {
          console.log('Card AID:', txnData.cardData.aid);
          console.log('App Name:', txnData.cardData.appName);
        }
      }
    } else {
      console.log('Sale failed:', response.rspMsg);
    }
  } catch (error) {
    console.error('Sale error:', error);
  }
};

// Example: Process sale for 10.00 (amount is a number, e.g., 10.00)
const messageId = `Pos-${Date.now()}`; // Generate unique message ID
processSale(10.0, messageId);
```

--------------------------------

### Initialize SoftPOS SDK with NGHeadlessSetup

Source: https://docs.neurogine.com/suite-sdk/api-reference/headless-setup

Initializes the SoftPOS SDK using the `initSoftPos` method. This is a suspended method that requires a coroutine context and should be called at application startup. It takes the application instance and the license file name as parameters, returning an SDK initialization response.

```kotlin
val initResult = NGHeadlessSetup.initSoftPos(application, "license_file_name")
// Success(value=SdkInitResp(sdkVersion=1.10.105.12.17, sdkId=4411be126c0c91b7))
```
Tokens:
Raw