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
Feature | Comments |
---|---|
Card Payments - Geidea Hosted Form | |
Card Payments - Merchant Hosted Form | Merchants will need to be PCI-DSS certified |
Hosted Payment Page Solution |
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.
Software | Version |
---|---|
Android | 6.0.0 or greater |
Java | 8.0.0 or greater |
Kotlin | 1.7.20 or greater |
Android SDK | 5.2.0 or greater |
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.
- 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}
- Extract the Geidea_5.0.0.zip file with the below command:
unzip -o Geidea_5.0.0.zip
- Proceed to update your build.gradle files to access the local maven repository.
buildscript {
repositories {
// ...
mavenLocal()
}
}
allprojects {
repositories {
// ...
mavenLocal()
}
}
- 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:
- 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. - 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()
}
}
}
Updated 1 day ago