Getting Started

The Merchant Embed PayContactless SDK enables seamless contactless payment and refund operations from your React Native application. The SDK handles payment transaction UI internally, provides querying of transaction history, daily summaries, and lot more.

Integrators must initialize the SDK early in the app lifecycle to ensure proper transaction handling.

Prerequisites

Before integrating this SDK, ensure you have:

• API Key, Organization ID, Google Cloud ID learn more on SDK Initialization section to understand how to get this parameters.

• Merchant ID, Terminal ID, Phone Number, Business Name

• React Native dependencies installed in your project, preferably;

"react": "19.2.0" or updward,
"react-native": "0.83.1" or upward

To download the PayContactless embedded SDK, you will be provided with secure credentials (username and password).

Follow the steps below to configure your project and fetch the SDK dependency.

Supported Android SDKs

• Minimum Android SDK: 30

• Kotlin minimum version: 1.9

• Minimum Android NDK version: 26.+

Add the required permissions in android directory AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

 <uses-permission android:name="android.permission.NFC" />
 <uses-permission android:name="android.permission.READ_PHONE_STATE" />
 <uses-feature android:name="android.hardware.nfc" android:required="false" />

No custom activities are required. The SDK handles UI internally.

Add the Maven repository block to your android directory:

• settings.gradle

We recommend keeping the credential in your gradle.properties file, and avoid committing this file to your repo.

You can ignore this in git by adding it to .gitignore

Groovy DSL

def libUser = hasProperty('YOUR USERNAME') ? YOUR USERNAME : ""
def libPass = hasProperty('YOUR PASSWORD') ? YOUR PASSWORD : ""
//dependencyResolutionManagement block
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        flatDir {
            dirs 'libs'
        }

        maven {
            url "https://nexus.prophius-api.com/repository/maven-releases/"
            credentials {
                username = libUser
                password = libPass
            }
        }
    }
}

We recommend using the following version of ndkd kotlin.

Add this to your project level buildscript block, and your reference in your app level android block, accordingly.

ndkVersion = "27.1.12297006"
kotlinVersion = "2.1.20"

Add the SDK dependency in your module level build.gradle file of the project like below.

implementation 'com.prophius:paycontactlesssdk.embed.stage:3.4.17'

SDK does not allow to run the app on debug. The application must be release build.

Check Security Mechanisms section for the other restriction.

Security Mechanisms

This version of the SDK must be used in integration phase by developer. For the internal and external tests, the version of SDK must never be used.

Required Dependencies

SDK needs some third party libraries and the integrator app must have these dependencies. The libraries which is shared below should be added to the build.gradle file.

// Room
    implementation "androidx.room:room-runtime:2.7.0"
    annotationProcessor "androidx.room:room-compiler:2.7.0"
// SQLCipher
    implementation "net.zetetic:android-database-sqlcipher:4.5.0"
// Gson
    implementation 'com.google.code.gson:gson:2.10.1'
// Lottie
    implementation "com.airbnb.android:lottie:3.4.0"
// Google Play Services
    implementation 'com.google.android.gms:play-services-base:18.6.0'
// Google Play Integrity
    implementation 'com.google.android.play:integrity:1.4.0'
// OkHttp3
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.10.0'
// Android appcompact & material ui
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation 'com.google.android.material:material:1.9.0'

In order to support schemas' branding animations, jetifier tools must be enabled on your project. The following configuration must be added on your gradle.properties file.

# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

Using the Merchant PayContactless Embed SDK Library

SDK Initialization

In your Application class onCreate() method, initialize the SDK:

override fun onCreate( {
super.onCreate()PayContactlessEmbed.getInstance().start(this, orgID, googleCloudID)
}

• Must be called before performing any transactions

• Ensures the SDK is ready for doSale, payWithLink,payWithAccount and other major payment flows

Required Parameters:

• Context: Application context

• Organization Id: Predefined organization identenfier

• Google Clould Project Number: Project Number of your project on Google Cloud

PayContactless Embed SDK uses Play Integrity API for Automatic integrity protection. You need to enable Integrity API on your project and share required credentioans to the PayContactless team. Please check Play Integrity Configuration section.

Play Integrity Configuration

Remember to pass the these parameters as arguments when invoking the start method.

By adhering to these steps, you'll ensure the proper and utilization of the PayContactless Embed SDK library functions.

The SDK needs the activity result to parse the Payment activity reponse. The onAcitivtyResult method of the SDK must be called in MainActivity onActivityResult method.

PayContactlessEmbed.getInstance().onActivityResult(requestCode,resultCode,data)

A sample usage is highlighted below;

  override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        PayContactlessEmbed.getInstance().onActivityResult(requestCode,resultCode,data)
    }

Creating a React Native Bridge

Create a module class PayContactlessSDKModule in the android directory extending ReactContextBaseJavaModule and expose all public APIs using @ReactMethod.

All methods return Promises and JSON responses (where applicable). Some methods like doSale or payWithLink require currencyCode, e.g 566 is Naira Code.

A simple usage is highlighted below;

Please note that SDK Initialization API is different from the start method, and it has be called before every other public APIs.

import androidx.fragment.app.FragmentActivity
import com.facebook.react.bridge.*
import com.google.gson.Gson
import com.prophius.paycontactlesssdk.*
import java.util.HashMap

class PayContactlessSDKModule(
    reactContext: ReactApplicationContext
) : ReactContextBaseJavaModule(reactContext) {

    override fun getName(): String = "PayContactlessSDKModule"

    private val activity: FragmentActivity?
        get() = reactApplicationContext.currentActivity as? FragmentActivity

    /* --------------------INIT -------------------- */

    @ReactMethod
    fun initialize(apiKey: String, merchantInfo: ReadableMap, promise: Promise) {
        android.util.Log.d("PayContactless", "BRIDGE_HIT: Method entered")

        val merchant = MerchantInfo(
            merchantInfo.getString("merchantId") ?: "",
            merchantInfo.getString("terminalId") ?: "",
            merchantInfo.getString("phoneNumber") ?: "",
            merchantInfo.getString("businessName") ?: ""
        )

        val act = reactApplicationContext.currentActivity as? FragmentActivity
        if (act == null) {
            android.util.Log.e("PayContactless", "ERROR: Activity is null")
            promise.reject("NO_ACTIVITY", "Current activity is null")
            return
        }

        act.runOnUiThread {
            android.util.Log.d("PayContactless", "UI_THREAD: Executing SDK Init")
            try {
                // Your existing MerchantInfo setup...
                PayContactlessEmbed.getInstance().initialize(apiKey, merchant, object : InitializeListener {
                    override fun onSuccess(result: String?) {
                        val out = result ?: "INITIALIZED_BUT_STRING_WAS_NULL"
                        android.util.Log.d("PayContactless", "SDK_SUCCESS: $out")
                        promise.resolve(out)
                    }
                    override fun onFailure(error: Error) {
                        android.util.Log.e("PayContactless", "SDK_FAILURE: ${error.message}")
                        promise.reject("INIT_FAILED", error.message)
                    }
                })
            } catch (e: Exception) {
                promise.reject("CRASH", e.message)
            }
        }
    }



    /* -------------------- SALE -------------------- */

    @ReactMethod
    fun doSale(
        amount: String,
        description: String,
        currencyCode: String,
        promise: Promise
    ) {
        val act = activity
        if (act == null) {
            promise.reject("NO_ACTIVITY", "Current activity is null")
            return
        }

        act.runOnUiThread {
            PayContactlessEmbed.getInstance().doSale(
                amount,
                description,
                currencyCode,
                act,
                HashMap(),
                TransactionResultListener { result ->
                    promise.resolve(Gson().toJson(result))
                }
            )
        }
    }

Below are the other available public APIs within our SDK.

refundInquiry

refundInquiry(transactionCode?: string): Promise<string>

doFullRefund

doFullRefund(amount: string, transactionCode: string, description: string, currencyCode: string): Promise<string>

doPartialRefund

doPartialRefund(amount: string, transactionCode: string, description: string, currencyCode: string): Promise<string>

getTransactionHistory

getTransactionHistory(page: string, size: string, direction?: string, transactionCode?: string, startDate?: string, endDate?: string, startAmount?: string, endAmount?: string): Promise<string>

getTransactionDetail

getTransactionDetail(transactionId: string): Promise<string>

sendReceipt

sendRecipt(transactionId: string, email: string): Promise<string>

getDailySummary

getDailySummary(): Promise

sendDailySummary

sendDailySummary(): Promise<string>

doPreAuth

doPreAuth(amount: string, description?: string): Promise<string>

preAuthInquiry

preAuthInquiry(transactionCode?: string): Promise<string>

doPostAuth

doPostAuth(amount: string, transactionCode: string, description?: string, currencyCode: string): Promise