This guide helps developers create next-generation mobile experiences.
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
app
module-
Contains the sample merchant app
-
Depends on:
payment-sdk
payment-sdk-core
- Popular Android libraries: RxJava, Retrofit, OkHttp, Glide
payment-sdk
module
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
payment-sdk-core
module- Provides shared interfaces and classes used by other SDK modules

Android SDK App 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:
- Open the project in Android Studio.
- Allow Gradle to sync and download dependencies.
- 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
-
Open Android Studio.
Open Project - Android Studio
-
Select "Open an existing project" from the welcome screen.
-
Browse to the folder where you cloned the SDK (
payment-sdk-android
). -
Select the root directory and click Open.
-
Allow Gradle to sync and download any missing dependencies.
-
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
- Install the
dotenv
packagenpm install dotenv
- Open the app.js file
- Add the following line to the file:
require('dotenv').config();
- Add your merchant credentials and Payment Gateway endpoint in a
.env
file. - 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.

App Working
Step 3: Connect the App to the Server
- Open the
build.gradle (Module: app)
file. - Set the
buildConfigField
address 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.

Demo Store
Before testing payments, we need to add some settings.
-
First, tap the gear icon in the app's top right corner.
-
Next, tap the "+" next to "Merchant Attributes," add a key-value pair, and tap "Add."
Merchant Attributes
-
Then, tap the "+" next to "Environments."
-
Enter a Name, your API key, outlet reference, and realm (found in the portal), and tap "Add."
Add Environment
-
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.

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

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

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

Successful Payment.
SDK Payment Flow
When you tap PAY WITH CARD in the sample app:
-
The app requests a payment session from the sample merchant server.
-
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):
Currency | Exponent | Format |
---|---|---|
AED | 2 | major.minor |
AED 0.00 | → | 0.00 |
Card Payments
This section walks through how to initiate and handle card payments using the SDK.
Payment Flow
- Merchant App requests a payment session from your merchant server.
- Merchant Server returns payment session details.
- App calls
launchCardPayment()
with the required parameters. - SDK presents a card input form to the user and handles 3D Secure if necessary.
- Payment Gateway processes the payment and returns a result.
- 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
Status Code | Description |
---|---|
STATUS_PAYMENT_CAPTURED | Payment was successfully captured (SALE action). |
STATUS_PAYMENT_AUTHORIZED | Payment was successfully authorized (AUTH action). |
STATUS_PAYMENT_FAILED | Payment failed at the Payment Gateway. |
STATUS_GENERIC_ERROR | Generic client-side error (e.g., network issue or unexpected exception). |
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.
-
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.
-
Add SDK Modules to App Dependencies
-
Right-click your main app module and choose Open Module Settings.
-
In the Project Structure window:
- Go to the Dependencies tab.
- Click the + button and choose Module Dependency.
- In the list, select all the SDK modules (hold Shift to select multiple).
- Click OK.
-
Once added, your project is ready to use the SDK.
Using executeThreeDS()
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 inonActivityResult()
.
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)
-
Open your project in Xcode.
-
Go to File > Add Packages.
-
Enter the SDK repository URL:
https://github.com/network-international/payment-sdk-io
-
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
- Create or edit your
Podfile
in the root of your project:
target 'YourAppTarget' do
use_frameworks!
pod 'NISdk'
end
- Run the following in Terminal:
pod install
- Open the generated
.xcworkspace
file in Xcode.
Option 3: Carthage
If you're using Carthage:
-
Create a
Cartfile
in your project root:touch Cartfile
-
Add the SDK reference:
1. github "network-international/payment-sdk-ios"
-
Run the following to fetch dependencies:
carthage update
-
Link the framework:
- Drag
NISdk.framework
fromCarthage/Build/iOS
into your app's Linked Frameworks and Libraries in the project settings.
- Drag
-
Add a Run Script Phase to your build:
-
Go to Build Phases > + > New Run Script Phase.
-
Script content:
/usr/local/bin/carthage copy-frameworks
-
Input Files:
1. $(SRCROOT)/Carthage/Build/iOS/NISdk.framework
-
Output Files:
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:
- Create a Merchant ID in your Apple Developer account.
- Enable Apple Pay in your app capabilities.
- Configure your iTunes account to accept Apple Pay.
See Enable Apple Pay for a full guide.
i. Create a PKPaymentRequest
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 eventsoverParent
: the view controller presenting the Apple Pay sheetorderResponse
: returned from the Order APIpaymentRequest
: thePKPaymentRequest
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
Parameter | Description |
---|---|
cardPaymentDelegate | A delegate class that implements CardPaymentDelegate to handle callbacks. |
overParent | The view controller presenting the 3DS UI. |
paymentResponse | The response object from the saved card payment request API. |
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
Property | Description |
---|---|
primaryColor | Main color used for buttons and highlights |
secondaryColor | Background or accent color |
buttonTextColor | Text color for primary buttons |
navigationBarTintColor | Tint color for navigation 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.