Android SDK

This document presents the steps for integrating the Geidea payment gateway with your Android mobile application (app).

Overview

Android is a mobile operating system based on open-source software, designed primarily for touchscreen mobile devices such as smartphones and tablets. The Geidea Online Payments SDK is a wrapper that extends the Geidea Payment Gateway, allowing you to take payments through Geidea. You can easily accept credit card payments and other payments through wallet providers.

Integrating our payment gateway with your Android mobile app has never been easier. Through the Geidea Online Payments SDK, our payment gateway can be seamlessly integrated with just a few lines of code.

❗️

While we make every effort to test software or modules or plugin or SDK updates rigorously, there is no guarantee that a plugin or module or SDK would work seamlessly with your device. So please back up your mobile app before updating any plugins, or modules or SDKs. This helps you restore your website from backup in case you run into unexpected errors.

Software and plugin or module or SDK updates involve programming code changes. The updates may often request upgrades to the development environment or other hosting software.

Features

The Android SDK includes the below features

Pre-requisites

You will need a merchant account with Geidea and the following software running in your hosting environment to accept payments using the Geidea payment gateway.

👍

Sample App Code

We have created a sample app and shared the code here. The code consists of samples for you to use to accelerate your app development.

Installation Steps

Step 1 - Gradle setup

The SDK is available on the GitHub repository. You can download the latest version of the SDK from here. The SDK contains a file geidea.zip. Remove this file and follow the below instructions.

1. Download the Geidea_5.0.0.zip file to your local machine and add it to the following directory.

Download the zip file in the home directory of your local machine
/Users/{username}

2. Extract the Geidea_5.0.0.zip file with the below command:

unzip -o Geidea_5.0.0.zip

3. Proceed to update your build.gradle files to access the local maven repository.

buildscript {
  repositories {
	// ...
        mavenLocal()
    }
}
allprojects {
    repositories {
        // ...
        mavenLocal()
    }
}

4. Add the extracted SDK as a dependency in your app-level build.gradle

implementation 'net.geidea.paymentsdk:paymentsdk:<LATEST VERSION>'

SDK Initialization

Add the SDK to your project.

The integration starts by adding your merchant credentials (Merchant Public Key and API password) with the GeideaPaymentSdk.setCredentials()method. You can check if there credentials already stored with the GeideaPaymentSdk.hasCredentials. It is only important to be stored prior to using the SDK.
kotlin

if (!GeideaPaymentSdk.hasCredentials) {
    GeideaPaymentSdk.setCredentials(
            merchantKey = "<YOUR MERCHANT KEY>",
            merchantPassword = "<YOUR MERCHANT PASSWORD>"
    )
}

IMPORTANT:

1. The setCredentials() method can be used to store your credentials securely on the device by using encryption. So it is not required to set them on each app start event. You could set them once per installation of the app on the device.
2. As a good security and coding practice, do not hard-code your merchant password directly into your APK file. Always get it securely and dynamically (from the secure endpoint of your backend or some secure server) where the password has been stored with encryption.

The Flow concept

The SDK employs the concept of UI flow which is a sequence of UI screens, network calls and other operations that are orchestrated in a logical manner. UI flows are implemented based on the typical Android Activity results where one activity (or a chain of more activities) is launched with an input intent, then it performs its task(s) and finally produces some output which contains the result data you are interested in. Each flow is represented and managed by an ActivityContract implementation.

Using Activity result contracts

The latest version of Android platform now supports Activity Result APIs that offer a better experience instead of the traditional and now deprecated startActivityForResult() method. For more info please visit https://developer.android.com/training/basics/intents/result .

Payment flow

The Payment flow expects an input of type PaymentData and returns a result of type GeideaResult<Order>. The PaymentContract is used to manage the input/output parcelization.

Declare a launcher in your code from where you wish to start the payment.
kotlin

private var paymentLauncher: ActivityResultLauncher<PaymentData>

After declaring the launcher, register it with a PaymentContract instance and your
function or lambda that should accept the final result.

fun handleOrderResult(result: GeideaResult<Order>) {
    /** Handle the order response here */
}
paymentLauncher = registerForActivityResult(PaymentContract(), ::handleOrderResult)

Building your PaymentData

PaymentData contains details about the order, customer and preferred payment method. It has 2 mandatory properties - amount and currency.
kotlin

val paymentData = PaymentData {
    // Mandatory properties
    amount = 123.45
    currency = "SAR"
    // Optional properties
    paymentMethod = PaymentMethod {
        cardHolderName = "John Doe"
        cardNumber = "5123450000000008"
        expiryDate = ExpiryDate(month = 1, year = 25)
        cvv = "123"
    }
    callbackUrl = "https://website.hook/"
    merchantReferenceId = "1234"
    customerEmail = "[email protected]"
    billingAddress = Address(
            countryCode = "SAU",
            city = "Riyadh",
            street = "Street 1",
            postCode = "1000"
    )
    shippingAddress = Address(
            countryCode = "SAU",
            city = "Riyadh",
            street = "Street 1",
            postCode = "1000"
    )
}

PaymentData paymentData = new PaymentData.Builder()  
        .setAmount(123.45d)  
        .setCurrency("SAR")  
        .setPaymentMethod(new PaymentMethod.Builder()  
                .setCardHolderName("John Doe")  
                .setCardNumber("5123450000000008")  
                .setExpiryDate(new ExpiryDate(1, 25))  
                .setCvv("123")  
                .build()  
        )  
        .setCallbackUrl("<https://website.hook/">)  
        .setMerchantReferenceId("1234")  
        .setCustomerEmail("[email protected]")  
        .setBillingAddress(new Address(  
                "SAU",  
                "Riyadh",  
                "Street 1",  
                "1000"  
        ))  
        .setShippingAddress(new Address(  
                "SAU",  
                "Riyadh",  
                "Street 1",  
                "1000"  
        ))  
        .build();

Validations
The SDK carries out some basic validation checks on construction of the `PaymentData` and `PaymentMethod` objects. For example, whether the CVV is 3 or 4 digits. If any of the validation check does not pass then an `IllegalArgumentException` with a message is thrown. 
For a comprehensive list of validity conditions please refer to the Integration guide.

### Starting payment flow
After registering for results a payment flow can be started
```kotlin```

paymentLauncher.launch(paymentData)

### Receiving the Order result
The final result of the Payment flow is returned as a sealed object of type `GeideaResult<Order>`.

```kotlin```

fun handleOrderResult(result: GeideaResult<Order>) {  
    when (result) {  
        is GeideaResult.Success<Order> -> {  
            // Payment successful, order returned in result.data  
        }  
        is GeideaResult.Error -> {  
            when (result) {  
                is GeideaResult.NetworkError -> {  
                    // Client or server error  
                    handleNetworkError(  
                        result.responseCode,  
                        result.responseMessage,  
                        result.detailedResponseCode,  
                        result.detailedResponseMessage,  
                    )  
                }  
                is GeideaResult.SdkError -> {  
                    // An unexpected error due to improper SDK  
                    // integration or SDK internal bug  
                    handleSdkError(result.errorCode, result.errorMessage)  
                }  
            }  
        }  
        is GeideaResult.Cancelled -> {  
            // Payment flow cancelled by the user (e.g. Back button)  
            Toast.makeText(this, "Payment cancelled by the user",  
                           Toast.LENGTH_LONG).show()  
        }  
    }  
}