HomeMerchantsDevelopers

Android SDK

Introduction

Welcome to the Android Payment SDK Developer Guide. This guide shows you how to build a merchant app and get payment using Payment SDK.

The Android SDK may be found here:

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

Specifications

Android API Level
Android SDK and the sample merchant app support a minimum API level 19 (Android Kitkat).
For more details, please refer to Android API level requirements online: https://developer.android.com/guide/topics/manifest/uses-sdk-element#min

Development Environment

Android Payment SDK modules and the sample merchant app, Furniture Store Android App, are developed using the Kotlin programming language (version > 1.3 with stable Coroutine support) in Android Studio IDE. This is compatible with Android projects developed with Java language.

All background or IO operations are designed to run on Kotlin Coroutines framework. This reduces third party library dependencies on SDK modules, and avoids dependency conflicts with the existing merchant app libraries.

Languages

Android SDK supports English and Arabic.

Currencies

The Network International Payment Gateway currently supports Emirati Dirham (AED).
All valid currencies can be supported in SDK.

Getting Started

This section, Getting Started, shows you how to run the sample merchant app, Furniture Store Android App, and also how to import SDK modules into your existing Project.

Specifications
The sample merchant app is provided by Network International and contains the following Android Studio modules:

● app module
This is the main app module, and contains the sample merchant app source code.
The app module is dependent on SDK payment libraries (payment-sdk and payment-sdk-core) as well as other well-known Android frameworks and libraries: RxJava, Retrofit, OkHttp and Glide.

● payment-sdk module
This module contains the Android Pay Page source code for card payment.
The module handles getting card details from the User, and submitting payment requests to the Payment Gateway.
If 3D Secure is required with the existing payment flow, this will be handled by the page page as well. A successful or failed payment response will be returned to merchant app in an Intent bundle.

● payment-sdk-core module
This module contains the common interfaces and classes used by the other SDK modules.

862

Import and Run Sample Merchant App and Sample Merchant Server

Follow the procedures below to import and run the Sample Merchant App, Furniture Store Android App, and the Sample Merchant Server.

Import the Sample Merchant App:

This procedure shows you how to import the sample merchant app into Android Studio IDE, and run it on an emulator or real device.

  1. Run Android Studio.
  2. Click on the “Open an existing Android Studio project” menu option.
950
  1. Locate the sample app folder.
  2. Click the Open button to start importing project.
1598

Run the Sample Merchant Server

A sample merchant server will be provided to you. This is written in Node.JS. You can run the server locally and use it to test the sample app, Furniture Store Android App.
This procedure shows you how to install and run the sample merchant server.

  1. Ensure Node.JS is already installed on your computer.
  2. Locate the config.js to configure the sample merchant server.
    This file contains details about the merchant credentials and endpoints to reach Payment Gateway.
    Contact your Portal Admin to find out further details.
  3. To run the server, open Terminal on Mac or Command-Line on Windows.
  4. Type in the following code and press the Enter key:
    $ node server.js
  5. Open a browser window.
    Type in the following address and press the Enter key:

http://localhost:3000

The system checks the server is active and running. If not, check the NodeJS console (terminal window) for error logs for more information.
6. Go to the procedure below.

Run the Sample Merchant App

If the sample merchant server is active, a few more steps are needed to run sample app. This procedure shows you how to install settings and run the sample app.

    1. Open the build.gradle (Module: app) file.
      This sets the sample merchant server address IP address. If you are running merchant server locally and connecting over Android emulator, IP address should be set 10.0.2.2
1356
    1. Click the Play icon on the Android Studio toolbar menu. The merchant app plays on the emulator or a real device.

📘

Note

If using a real device, it should be connected to the same WIFI the merchant server is on. Make sure that sample server is reachable from the emulator or the real device.

1152
    1. When the Furniture Store Android App runs, you will see the following screens:.
574
    1. When the user clicks the PAY WITH CARD button, the sample merchant app gets payment details from the sample merchant server, and then passes control to SDK.

SDK has a built-in screen to collect the card details and handle the 3D Secure flow.
The two screens below show the SDK activity screens:

572

Payment API Reference

This section, Payment API Reference, shows how to use Payment SDK to build a merchant app and get payment.

Payment SDK contains a set of gradle modules for different payment methods. This lets developers incorporate payment with relatively minimum development effort.
Importing only required modules (i.e. just for the payment methods you will be using) into your Android Studio project will keep the final APK smaller, and make the building process faster.
payment-sdk and payment-sdk-core are the two main modules that should be imported into the gradle project to start using SDK.
The other modules are optional and should be imported only when a particular payment method is required.

Client

SDK provides the PaymentClient class to launch various payment methods and get payment in the merchant app.

PaymentClient requires an activity instance parameter to be instantiated. Please see the sample merchant app for more details about using PaymentClient. It requires an activity instance rather than a Context since card payment result could only return the result to a calling activity.

The following code shows how to construct PaymentClient by passing an Activity reference:

class PaymentClient(private val context: Activity)

Specifications

Amounts and fees in sdk are represented by BigDecimal inside the SDK.
An amount value has two parts: major and minor (the "exponent") currency units.
For AED currency, it has exponent 2 (10 to the power of 2 is 100)

AED 0.00 → AED major.minor

Card Payment

This section shows the possible steps that card payment contains.

Card Payment Process:

  1. The merchant app requests payment URL from the merchant server.
  2. The merchant server returns the required information.
  3. Merchant app launches card payment through SDK with required parameter.
  4. SDK gets the card details (PAN, CVV, expiry date and card holder) from the user, and make a http call to make payment.
  5. The payment gateway starts a 3D secure flow if required.
  6. The payment result is returned to SDK, and then to the merchant app in order.
831

Card Payment API

SDK provides a very simple API to be able to get payment using debit or credit cards.

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

The card payment API internally launches another activity to get card details from the user, and control payment/3D Secure flows between the payment gateway and the merchant app.
Once payment flow completes, onActivityResult is called on merchant’s activity (which is passed in constructor) and CardPaymentData type is returned in the data Intent.
requestCode is used to filter out activity result requests to find out where activity response comes from.
Please see HomeActivity.onActivityResult for more details in the sample merchant app or refer to the following code snippet to learn how to handle card payment response in your merchant app.

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()
       }
   }
}

You may notice that requestCode parameter is the same value as we already passed on to launchCardPayment method.

If the User presses the Back button and cancels the card payment flow, RESULT_CANCELED is returned as an activity resultcode.

📘

Note

➮ Further reading about this topic on the Android Developer Site: Getting a Result from an Activity

Result Code in CardPaymentData

View the following code snippet to see how merchant app handles result code in 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 Codes
Every possible result code is checked, and an appropriate action is taken:

● STATUS_PAYMENT_CAPTURED
shows order creation with “SALE” action parameter is successful.
● STATUS_PAYMENT_AUTHORIZED
shows order creation with “AUTH” action parameter is successful.
● STATUS_PAYMENT_FAILED
shows payment is not successful on payment gateway.
● STATUS_GENERIC_ERROR
shows possible issues on the client side, for instance, network is not accessible or an unexpected error occurs.

Creating Card Payment Request

Before launching card payment, CardPaymentRequest should be created using CardPaymentRequest.Builder class.

CardPaymentRequest.Builder needs only one parameter to create a valid request:

● gatewayUrl:
Merchant server starts a payment order creation and sends a payment URL back to the client.
Merchant app uses this URL to construct a card payment request.

Currency Units Conversion For Order Creation

Unlike SDK, all amount values should be translated into Integer before sending the payment amount to the gateway for starting order creation.
That means major and minor parts are sent as an one-integer unit.

AED → AED1.00 translates to 100
AED → AED3.99 translates to 399
USD → $1.00 translates to 100

Please see PaymentOrderApiInteractor class in the sample merchant app for more details.

Configuring Your Project Dependencies For Card Payment

This procedure shows you how to configure an Android Studio project, and how to add SDK modules into your project:

  1. Right click on your main app module and select the New|Import Modules... menu option. This option will import required SDK modules into your project.
1782
  1. Select the payment-sdk module folder and click the Open button.
    The payment-sdk module automatically imports any other required modules as well. This means you don’t have to add dependent modules manually. After this steps, all required modules will be imported in your project.
1596
  1. Right click on your main app module and select the Open Module Settings menu option. The Project Structure dialog is going to be displayed.
858
  1. Click on the Dependencies tab (1) to display the Dependencies tab page and click + button (2) to see popup menu and select the Module dependency option.
2036
  1. You will see the Choose Modules dialog and select all the SDK module dependencies in the list, using the left mouse button and Shift key.
2042
  1. Click the OK button. The SDK module dependencies are going to be imported into your project. Now, you are ready to use SDK.

Using the executeThreeDS SDK method

The executeThreeDS method can be used by customers integrating with the Android SDK to invoke the EMV 3-D Secure workflow on behalf of card-holders. It is typically used in conjunction with the savedCard (tokenization) functionality to provide a simple way of combining tokenized payment experiences with the security of an EMV 3-D Secure cardholder authentication step.

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

paymentResponse (in this context) is the complete JSON response sent by N-Genius Online to the merchant server for the savedCard payment request API.