Android SDK

Android SDK Overview

Welcome to the Android SDK Developer Guide for integrating payments via Network International. This SDK allows you to accept payments in your Android app using a prebuilt checkout flow and secure APIs.

You can find the SDK and sample app on GitHub:
👉 Android Payment SDK on GitHub

Requirements

Supported Android Version

• Minimum API level: 19 (Android 4.4, KitKat)
• See full compatibility guidelines in the Android SDK docs.

Development Environment

• Language: Kotlin (version 1.3+ with Coroutine support)
• IDE: Android Studio
• Compatible with Java-based Android projects

The SDK leverages Kotlin Coroutines for background and I/O operations to avoid conflicts with third-party dependencies and simplify integration.

Language and Currency Support

• Languages: English and Arabic
• Currencies: Supports AED (Emirati Dirham) by default. Other valid currencies are also supported—refer to the Payment Gateway for details.

Getting Started

To explore the SDK in action or begin integration, use the provided Furniture Store sample app or import the SDK modules directly into your own project.

Included Modules

app module

• Contains the sample merchant app

• Depends on:

  • payment-sdk
  • payment-sdk-core
  • Popular Android libraries: RxJava, Retrofit, OkHttp, Glide

payment-sdk module

• Implements the Pay Page for card-based payments
• Collects card details, handles 3D Secure (if required), and submits requests to the Payment Gateway
• Returns the result (success/failure) via an Intent bundle

payment-sdk-core module

• Provides shared interfaces and classes used by other SDK modules

Download the SDK and Sample App

To get started, clone the SDK and sample project from GitHub:

git clone https://github.com/network-international/payment-sdk-android.git

Alternatively, you can download the ZIP if you prefer not to use Git.

After downloading:

1. Open the project in Android Studio.
2. Allow Gradle to sync and download dependencies.
3. Run the Furniture Store sample app on your emulator or physical device.

📘

Make sure your device or emulator is running at least Android 4.4 (API19).

Run the Sample App and Merchant Server

To explore how the SDK works in a real-world scenario, you can use the provided Sample App and Sample Merchant Server. Follow the steps below to get everything up and running in your local environment.

📘

The sample merchant servers are available in two versions: PHP and JavaScript(Node.JS).

Step 1: Import the Sample Merchant App

1. Open Android Studio.

   

2. Select "Open an existing project" from the welcome screen.

3. Browse to the folder where you cloned the SDK (payment-sdk-android).

4. Select the root directory and click Open.

5. Allow Gradle to sync and download any missing dependencies.

6. Once the project loads, you’re ready to run the app in an emulator or on a real device.

Step 2: Run the Sample Merchant Server

A sample Node.js-based merchant server is included to simulate a backend environment. It handles communication with the Payment Gateway and serves mock payment data.

Prerequisites

• Node.js must be installed on your system.
  Download and install Node.js

🔧 Configuration

1. Install the dotenv package
   bash

   npm install dotenv
   

2. Open the app.js file
3. Add the following line to the file:
   Node.js

   require('dotenv').config();
   

4. Add your merchant credentials and Payment Gateway endpoint in a .env file.
5. The N-Genius portal provides these values.
   Click here to learn more .

Example .env file:

API_KEY=your_api_key_here
IDENTITY_API_URL=https://your.identity.api.url
GATEWAY_API_URL=https://your.gateway.api.url
PORT=3000
REALM=your_realm_here

Start the Server

Open a terminal in the project directory and run:

node app.js

Once the server is running, test it by opening:

http://localhost:3000/health

If the server does not load, check the terminal logs for errors.

Step 3: Connect the App to the Server

1. Open the build.gradle (Module: app) file.
2. Set the buildConfigFieldaddress of the merchant server.

Here's an example if you are running the server locally:

      debug {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
            buildConfigField "String", "BASE_URL", "\"http://10.0.2.2:3000/\""
        }

        release {
            minifyEnabled true
            shrinkResources true
            signingConfig signingConfigs.release
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
            buildConfigField "String", "BASE_URL", "\"http://10.0.2.2:3000/\""
        }

For physical devices, ensure both the device and your development machine are connected to the same Wi-Fi network.

Step 4: Run the Sample App

Click the Run (Play) button in Android Studio to launch the app.

When the sample app opens, you’ll see an interface with the option to make a payment.

Before testing payments, we need to add some settings.

1. First, tap the gear icon in the app's top right corner.

2. Next, tap the "+" next to "Merchant Attributes," add a key-value pair, and tap "Add."

   

3. Then, tap the "+" next to "Environments."

4. Enter a Name, your API key, outlet reference, and realm (found in the portal), and tap "Add."

   

5. Tap the back button to return to the home screen.

For more details, click here.

Step 4: Use the app to make a payment

To test payments, use the app to select any item(s) from the Home screen. Tap "Pay" to proceed. Get a test card here.

Enter the card details (any name, expiry, CVV) on the payment screen and tap "Make Payment".

The 3DS challenge screen will appear. Enter the one-time passcode (OTP) and tap "Submit." Note: This screen will not appear for frictionless transactions.

The app will authorize via 3DS, displaying a "Payment Success" message. Congratulations!

SDK Payment Flow

When you tap PAY WITH CARD in the sample app:

1. The app requests a payment session from the sample merchant server.

2. It then hands off control to the Payment SDK, which:

   • Displays a secure card entry form
   • Handles 3D Secure authentication (if required)
   • Returns a success or failure response to the app

Payment API Reference

Use the Payment SDK to easily integrate secure card payments into your Android app. This section outlines how to configure the SDK, initiate card payments, and handle results from the Payment Gateway.

SDK Modules

The SDK is modular—import only the components you need to keep your app lightweight and efficient.

Required Modules

At minimum, import the following Gradle modules:

payment-sdk
payment-sdk-core

Optional Modules

Other modules support specific payment methods. Only import those relevant to your integration to reduce your APK size and build time.

PaymentClient

The PaymentClient class is your main entry point to initiate and manage payment flows from within your app.

🔧 Initialization

You must instantiate PaymentClient using an Activity (not just a Context), since payment results are returned via onActivityResult().

class PaymentClient(private val context: Activity)

For usage examples, refer to the sample Furniture Store Android App.

Amount Representation

Amounts in the SDK are represented using BigDecimal.

Each currency has a specific exponent (e.g. 2 for AED, meaning values are in hundredths):

Card Payments

This section walks through how to initiate and handle card payments using the SDK.

Payment Flow

1. Merchant App requests a payment session from your merchant server.
2. Merchant Server returns payment session details.
3. App calls launchCardPayment() with the required parameters.
4. SDK presents a card input form to the user and handles 3D Secure if necessary.
5. Payment Gateway processes the payment and returns a result.
6. SDK returns the result to the merchant app via onActivityResult().

Launch a Card Payment

Use the following method to launch a card payment:

paymentClient.launchCardPayment(
    request: CardPaymentRequest,
    requestCode: Int
)

This internally launches an activity to collect card details and manage the 3D Secure flow. When the payment is complete, onActivityResult() is triggered in your calling activity.

Handle the Result

Example of handling the card payment result:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    
    if (requestCode == CARD_PAYMENT_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> onCardPaymentResponse(
                CardPaymentData.getFromIntent(data!!)
            )
            Activity.RESULT_CANCELED -> onCardPaymentCancelled()
        }
    }
}

📘

If the user cancels the payment (e.g. presses Back), RESULT_CANCELED is returned

Result Codes

Once the SDK returns control, you can evaluate the outcome using CardPaymentData:

override fun onCardPaymentResponse(data: CardPaymentData) {
    when (data.code) {
        CardPaymentData.STATUS_PAYMENT_AUTHORIZED,
        CardPaymentData.STATUS_PAYMENT_CAPTURED -> {
            view.showOrderSuccessful()
        }
        CardPaymentData.STATUS_PAYMENT_FAILED -> {
            view.showError("Payment failed")
        }
        CardPaymentData.STATUS_GENERIC_ERROR -> {
            view.showError("Generic error (${data.reason})")
        }
        else -> IllegalArgumentException("Unknown payment response (${data.reason})")
    }
}

Result Code Descriptions

📘

Learn more: Getting a result from an Activity (Android Developer Site)

Create a Card Payment Request

Before launching a card payment, you need to create a CardPaymentRequest object using the CardPaymentRequest.Builder class.

The Builder requires only one parameter to create a valid request:

• gatewayUrl – This URL is provided by the merchant server after initiating order creation. The merchant app uses this URL to build the card payment request.

Currency Units for Order Creation

Unlike the SDK, which uses BigDecimal, the payment gateway requires amount values to be sent as an integer during order creation. This integer represents the full amount in the smallest currency unit.

Examples:

• AED 1.00 → 100
• AED 3.99 → 399
• USD 1.00 → 100

Refer to the PaymentOrderApiInteractor class in the sample merchant app for more information.

Configure Project Dependencies

Follow the steps below to import the SDK modules into your Android Studio project.

1. Import SDK Modules

   • Right-click your main app module and choose New > Import Module...
   • Select the payment-sdk folder and click Open.
   • The payment-sdk module will automatically pull in any additional dependencies.

2. Add SDK Modules to App Dependencies

   • Right-click your main app module and choose Open Module Settings.

   • In the Project Structure window:

     1. Go to the Dependencies tab.
     2. Click the + button and choose Module Dependency.
     3. In the list, select all the SDK modules (hold Shift to select multiple).
     4. Click OK.

Once added, your project is ready to use the SDK.

Using executeThreeDS()

The SDK provides an executeThreeDS() method that allows you to trigger the EMV 3-D Secure flow. This is useful when integrating tokenized payments (e.g. saved cards) and want to authenticate the cardholder securely.

paymentClient.executeThreeDS(
    paymentResponse: PaymentResponse,
    requestCode: Int
)

• paymentResponse is the full JSON response returned from the N-Genius Online saved card payment API.
• requestCode helps distinguish this callback in onActivityResult().

Customize SDK UI Colors

You can customize the Payment SDK’s color scheme to match your brand. To do this, override specific color resources in your project’s resource files (colors.xml).

Example:

<color name="sdk_primary_color">#FF6200EE</color>
<color name="sdk_secondary_color">#FF03DAC5</color>

Refer to the SDK theming documentation (or contact your relationship manager) for the full list of customizable keys.

Step 1: Install the iOS SDK

The N-Genius iOS SDK supports apps running on iOS 11 or later. You can install the SDK using Swift Package Manager, CocoaPods, or Carthage, depending on your project setup.

Option 1: Swift Package Manager (Recommended)

1. Open your project in Xcode.

2. Go to File > Add Packages.

3. Enter the SDK repository URL:

   Text

   https://github.com/network-international/payment-sdk-io
   

4. Choose the version range and add the package to your target.

📘

Swift Package Manager offers a seamless setup and is preferred for most modern iOS projects.

Option 2: CocoaPods

1. Create or edit your Podfile in the root of your project:

target 'YourAppTarget' do
  use_frameworks!
  pod 'NISdk'
end

2. Run the following in Terminal:

pod install

3. Open the generated .xcworkspace file in Xcode.

Option 3: Carthage

If you're using Carthage:

1. Create a Cartfile in your project root:

   sh

   touch Cartfile
   

2. Add the SDK reference:

   nginx

   1. github  "network-international/payment-sdk-ios"
   

3. Run the following to fetch dependencies:

   sh

   carthage update
   

4. Link the framework:

   • Drag NISdk.framework from Carthage/Build/iOS into your app's Linked Frameworks and Libraries in the project settings.

5. Add a Run Script Phase to your build:

   • Go to Build Phases > + > New Run Script Phase.

   • Script content:

     
     
     sh

     /usr/local/bin/carthage copy-frameworks
     

   • Input Files:

     shell

     1. $(SRCROOT)/Carthage/Build/iOS/NISdk.framework
     

   • Output Files:

     JavaScript

     1.  $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/NISdk.framework
     

Next Steps

Once the SDK is installed, you’re ready to initialize it and start integrating payments into your app. Continue to Step 2: Configure the SDK ›

Step 2: Using the SDK

Once the SDK is installed, you’re ready to start processing payments. The typical payment journey begins with creating an order, followed by collecting the customer’s payment via card or Apple Pay.

📘

Before proceeding, ensure you've acquired your authentication credentials. For help with this step, please contact your onboarding representative.

1. Creating an Order

To accept in-app payments, an order must first be created via your backend.

• Your mobile app sends the order request to your backend server.
• Your backend then calls the N-Genius Order API to generate the order securely.

Integrate the order API on your server using this guide.
For details on creating orders via the API, see our Create Order guide.
A sample merchant server is also available for reference.

📘

Server-side order creation is crucial for credential protection.

2. Accepting Card Payments

Once the order is created, you can present the card payment UI in your app.

Import the SDK into your view controller:

import NISdk

Implement CardPaymentDelegate methods to handle payment events:

class YourViewController: UIViewController, CardPaymentDelegate {

  func paymentDidComplete(with status: PaymentStatus) {
    switch status {
    case .PaymentSuccess:
      // Payment succeeded
    case .PaymentFailed:
      // Payment failed
    case .PaymentCancelled:
      // User cancelled payment
    }
  }

  func authorizationDidComplete(with status: AuthorizationStatus) {
    if status == .AuthFailed {
      // Authentication failed
    }
    // Authentication successful
  }

  func showCardPaymentUI(orderResponse: OrderResponse) {
    let sdk = NISdk.sharedInstance
    sdk.showCardPaymentViewWith(
      cardPaymentDelegate: self,
      overParent: self,
      for: orderResponse
    )
  }
}

📘

Note:

CardPaymentDelegate handles all payment-related events.
overParent refers to the view controller presenting the payment UI.
orderResponse is returned from the Order API.

3. Accepting Apple Pay Payments

To enable Apple Pay in your app:

1. Create a Merchant ID in your Apple Developer account.
2. Enable Apple Pay in your app capabilities.
3. Configure your iTunes account to accept Apple Pay.

📘

See Enable Apple Pay for a full guide.

i. Create a PKPaymentRequest

func createPKPaymentRequest(items: [PurchasedItems], total: Double) {
  let paymentRequest = PKPaymentRequest()
  paymentRequest.merchantIdentifier = merchantId
  paymentRequest.countryCode = "AE"
  paymentRequest.currencyCode = "AED"
  paymentRequest.requiredShippingContactFields = [.postalAddress, .emailAddress, .phoneNumber]
  paymentRequest.requiredBillingContactFields = [.postalAddress, .name]
  paymentRequest.merchantCapabilities = [.capabilityDebit, .capabilityCredit, .capability3DS]

  paymentRequest.paymentSummaryItems = items.map {
    PKPaymentSummaryItem(label: $0.name, amount: NSDecimalNumber(value: $0.amount))
  }
  paymentRequest.paymentSummaryItems.append(
    PKPaymentSummaryItem(label: "Total", amount: NSDecimalNumber(value: total))
  )
}

📘

Check out the included Swift and Objective-C example apps in this repository; they'll help you integrate the SDK.

ii. Present the Apple Pay Sheet

func presentApplePay() {
  let sdk = NISdk.sharedInstance
  sdk.initiateApplePayWith(
    applePayDelegate: self as? ApplePayDelegate,
    cardPaymentDelegate: self,
    overParent: self,
    for: orderResponse,
    with: paymentRequest
  )
}

📘

Note:

• cardPaymentDelegate: your class handling card events
• overParent: the view controller presenting the Apple Pay sheet
• orderResponse: returned from the Order API
• paymentRequest: the PKPaymentRequest object

4. Set the SDK Language (Optional)

You can localise the SDK UI by setting the language:

NISdk.sharedInstance.setSDKLanguage(language: "ar") // Arabic

Supported languages include "en" for English and "ar" for Arabic.

Using 3-D Secure (executeThreeDSTwo)

The executeThreeDSTwo method is used to initiate EMV® 3-D Secure (3DS2) authentication for saved cards (tokenized payments). This helps you combine the convenience of saved cards with the added security of cardholder verification.

This method is most commonly used when integrating saved card (tokenized) payments, providing frictionless but secure user experiences.

Swift Example

NISdk.sharedInstance.executeThreeDSTwo(  
    cardPaymentDelegate: self,  
    overParent: self,  
    for: paymentResponse  
)

Parameters

📘

paymentResponse should be the full JSON response returned by the N-Genius server when you initiate a saved card (tokenized) payment.

Customizing the SDK UI Theme

The Payment SDK allows you to personalize the look and feel of the payment screens to match your app’s branding. You can customize key visual elements like colors using the SDKColors class.

Example (Swift)

let sdkColors = SDKColors()
sdkColors.primaryColor = UIColor.systemBlue
sdkColors.secondaryColor = UIColor.white
sdkColors.buttonTextColor = UIColor.white
sdkColors.navigationBarTintColor = UIColor.black

NISdk.sharedInstance.setSDKColors(sdkColors)

Customizable Elements

📘

Use this feature to align the payment UI with your brand and deliver a seamless customer experience.

Webhooks and Mobile SDKs

Mobile apps cannot receive Webhooks directly. Because the final payment status is not always known by the time your customer returns to the app, it's important not to rely solely on in-app responses for order completion or fulfilment.

Instead, set the webhookUrl parameter when creating your payment order to point to a trusted server-side endpoint. Your backend will receive asynchronous payment status updates from the payment gateway.

To notify your mobile app of the final payment result:

• Implement a webhook handler on your backend to listen for payment status updates.

• Once the payment is confirmed or failed, your backend can trigger an update to the mobile app via one of the following:

  • Silent push notification to wake the app and update the UI
  • Polling (less efficient, only if push isn’t viable)
  • Firebase Cloud Messaging (FCM)

This approach ensures that your app reflects the true final payment status, regardless of whether the app is foregrounded, backgrounded, or closed when the payment is completed.

See our webhooks guide for a complete list of features.