Date: February 27, 2024

Integrate with Android SDK

The PortOne Android SDK offers merchants a seamless way to integrate the PortOne Payment Gateway into their Android applications, enabling them to accept payments securely and efficiently. This SDK serves as a bridge between a merchant's app and the PortOne Payment Gateway, providing a comprehensive set of tools and features tailored specifically for handling payment transactions.

The PortOne Android SDK empowers merchants to unlock the full potential of their Android applications by seamlessly integrating a reliable and secure payment gateway, enhancing user experience, and driving business growth through efficient payment processing capabilities

---

Video Tutorial

The following two video tutorials provide a detailed guide on integrating the PortOne Android SDK with your application to enable seamless payment processing:

Part-1: Installation of Android Native SDK

• In this tutorial, you will learn how to install the PortOne Android Native SDK in your Android application. The video will walk you through the process of adding the SDK as a dependency and authorising it, setting the foundation for integrating the PortOne Payment Gateway. Part-1 : Installation of Android Native SDK

Part 2: Initialising the SDK and Setting Intent Filters

• The second part of the tutorial focuses on initializing the PortOne SDK within your application and setting up intent filters to receive payment status updates. By following these steps, you will establish the necessary components for a smooth payment processing flow within your Android app. Part 2: Initialise the SDK and Set Intent Filters to receive the Payment Status

---

Sample App

Check the sample app to integrate on GitHub

---

Prerequisites

• **Create an account on PortOne:** Before proceeding with the integration, ensure you have created an account on PortOne to access their services and functionalities.
• Enable Payment Channels and Methods: Customize and enable the specific payment channels and methods that align with your business requirements and preferences.
• Access API KeysLogin to the portone portal where you can access the API Keys (portone key and secret key) for integrations under Settings -> API tab.
• authKey to access the SDK: Obtain an authorization key (authKey) from the PortOne Team, as it is required to securely access and utilize the features of the PortOne SDK in your Android application. authKey will be issued by the PortOne Team by sending us email on this in.dev@portone.io

---

Integration

Steps to integrate your Android application with PortOne Android SDK.

1. Install PortOne Android SDK and Authorise it.
2. Initialise the PortOne Instance
3. Set the Intent Filters in the Manifests
4. Set Intent Receivers for Payment Status
5. Setup to Obtain JWT Token from the Server

---

1. Install PortOne Android SDK and Authorise it.

1. Add the PortOne Android SDK as a dependency in your application's build.gradle file.

implementation 'com.github.iamport-intl:chaipay-android-native-sdk:V3.0.37'

2. Authorise the SDK using the provided authKey in your gradle.properties file.

authKey= XXXXXXXXXXXXXXXXXXXXXX

💡 *authKey will be issued by the PortOne Team. 1.* Send an email to [in.dev@portone.io](mailto:in.dev@portone.io) to request the authKey.

3. To utilize the authKey for accessing the PortOne SDK in your project's build.gradle or settings.gradle, you can follow these steps:

   1. Build.gradle (:Project) Setup:

      repositories {

      maven { url '<https://maven.google.com/>' }

      maven{

      url '<https://jitpack.io>'

      credentials { username authKey }

      }

      }

   2. Settings.gradle Setup:

      dependencyResolutionManagement {

      repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

      repositories {

      google()

      maven {

      url 'https://maven.google.com/'

      }

      maven {

      url 'https://jitpack.io'

      credentials { username authKey } // Add your generated authKey here

      }

      }

      }

4. To include the necessary lines of code in your build.gradle (:Project) file, mentioning the project dependency and specifying the Kotlin version, you can follow this structure:

   buildscript {

   ext.kotlin_version = "1.5.10" // Specify the Kotlin version here

   repositories {

   google()

   jcenter()

   }

   dependencies {

   classpath "com.android.tools.build:gradle:4.2.2" // Add the Android Gradle plugin version

   // Add any other dependencies needed for your project setup

   }

   }

---

2. Initialise the PortOne Instance:

1. Create an instance of the PortOne SDK in the activity where the payment checkout process occurs.
2. Initialise the SDK with the appropriate environment (sandbox or live).

private var environment = "sandbox" // Set environment to "sandbox" for testing

// For live environment uncomment the line below and comment the sandbox line

// private var environment = "live" // Set environment to "live" for production

private lateinit var portOne: PortOne

portOne = PortOneImpl(this, environment) // Initialize PortOne with the selected environment

---

3. Set the Intent Filters in the Manifests

To add an Intent Filter to the activity in your AndroidManifest.xml file so that users are navigated to a specific activity (default being Checkout Activity) after payment completion

<activity android:name=".CheckoutActivity">

<intent-filter>

<action android:name="android.intent.action.VIEW" />

<category android:name="android.intent.category.DEFAULT" />

<category android:name="android.intent.category.BROWSABLE" />

<data

android:scheme="portone"

android:host="checkout" />

</intent-filter>

</activity>

In this setup:

• The <activity> tag specifies the activity to which the Intent Filter applies.
• The <intent-filter> block defines the conditions under which the activity should be launched.
• The <data> tag specifies the scheme and host required in the incoming Intent for it to be directed to this activity after payment completion.

Update the activity name (e.g., .CheckoutActivity) as per your actual activity name and place this Intent Filter configuration within the corresponding <activity> tag in the AndroidManifest.xml file to handle post-payment navigation effectively.

By configuring the scheme as "portone" and host as "checkout" within the <data> tag of the Intent Filter, your Android application will be able to intercept the redirection URL with the format "portone://checkout" and navigate the user to the specified activity (e.g., CheckoutActivity) after payment completion. Adjust the activity name in the configuration according to your actual activity name for proper redirection handling.

---

4. Set Intent Receivers for Payment Status:

Implement intent receivers and listeners to receive payment status updates within your application.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {

super.onActivityResult(requestCode, resultCode, data)

if (resultCode == RESULT_CODE && data != null) {

when (requestCode) {

PAYOUT_REQUEST_CODE, PAYMENT_STATUS_REQUEST_CODE -> {

val paymentStatus: PaymentDto.PaymentStatus? =

(data.getSerializableExtra(PAYMENT_STATUS)

?: "Empty") as PaymentDto.PaymentStatus

if (paymentStatus != null) {

val resultToShow = paymentStatus.status + "\n" +

paymentStatus.status_code + "\n" +

paymentStatus.status_reason + "\n" +

paymentStatus.chaipay_order_ref + "\n" +

paymentStatus.channel_order_ref + "\n" +

paymentStatus.merchant_order_ref + "\n"

Log.i(TAG_PortOne, "Result To Show-> $paymentStatus")

tvPaymentStatus.text = resultToShow

}

}

}

}

}

The provided method onActivityResult is essential for handling the result of a launched activity, which in this case is used to receive the checkout status after completing a payment. Here's a breakdown of the functionality in the method:

1. Handle Payment Status Response:
   • Extract the payment status information from the received Intent based on the request code.
   • Populate the paymentStatus object with the relevant data from the Intent extras.
2. Display Payment Status in the UI:
   • Concatenate the payment status details into a formatted string for display.
   • Update the UI element (e.g., tvPaymentStatus) with the formatted payment status information.

This implementation allows your Checkout Activity to process the payment status response efficiently and update the UI accordingly based on the received payment status data.

---

5. Have a setup to get JWT token from the server

To set up the process of obtaining a JWT token from the server, you need to construct a JWT token that accepts the portoneKey as input. Here's an outline of the steps involved in setting up this process:

1. JWT Token Construction:

   Implement the server-side logic to generate a JWT token using the portoneKey as a key component of the token payload.

2. Token Retrieval in Android App:

   • Implement logic in your Android application to make a server request to retrieve the JWT token using the portoneKey.
   • Receive and store the returned token securely within the app for subsequent API authentication.

Authentication | PortOne

---

Android Embed

PortOne's Checkout offers a streamlined integration experience, simplifying the process for merchants. This variant involves calling a single method with the essential payload, which results in the PortOne SDK opening a webpage seamlessly. By handling the user interface within the SDK, merchants can focus on the payment flow without concerns about UI intricacies.

---

Video Tutorial

Web Checkout Process

---

Implementation

This is the method that has been utilised to process the web checkout.

val checkoutDetails = CheckoutPaymentDto.CheckoutUsingWebRequest()

portone.checkoutUsingWeb(

token = getJwtToken(portOneKey),

clientKey = clientKey,

request = checkoutDetails

)

Parameters	Data Type
token	String	mandatory
portOneKey	String	mandatory
request	CheckoutPaymentDto.CheckoutUsingWebRequest	mandatory

CheckoutPaymentDto.CheckoutUsingWebRequest

All of the web checkout request's parameters are listed here, along with the appropriate data type.

Parameters	Data Type
portoneKey	String	mandatory
merchantDetails	CheckoutPaymentDto.MerchantDetails
merchantOrderId	String	mandatory
amount	Double	mandatory
currency	String	mandatory
countryCode	String	mandatory
billingDetails	CheckoutPaymentDto.BillingDetails	Optional
shippingDetails	CheckoutPaymentDto.ShippingDetails	Optional
orderDetails	List< CheckoutPaymentDto.OrderDetail>	Optional
successUrl	String	mandatory
failureUrl	String	mandatory
expiryHours	Int	mandatory
source	String	mandatory
description	String	Optional
showShippingDetails	Boolean	Optional
showBackButton	Boolean	Optional
defaultGuestCheckout	Boolean	Optional
isCheckoutEmbed	Boolean	Optional
redirectUrl	String	mandatory
environment	String	mandatory

CheckoutPaymentDto.MerchantDetails

Parameters	Data Type
name	String	Optional
logo	String	Optional
backUrl	String	Optional
promoCode	String	Optional
promoDiscount	Int	Optional
shippingCharges	Double	Optional

CheckoutPaymentDto.BillingDetails

Parameters	Data Type
shippingName	String	Optional
shippingEmail	String	Optional
shippingPhone	String	Optional
shippingAddress	CheckoutPaymentDto.Address	Optional

CheckoutPaymentDto.ShippingDetails

Parameters	Data Type
billingName	String	Optional
billingEmail	String	Optional
billingPhone	String	Optional
billingAddress	CheckoutPaymentDto.Address	Optional

CheckoutPaymentDto.Address

Parameters	Data Type
city	String	Optional
countryCode	String	Optional
locale	String	Optional
line_1	String	Optional
line_2	String	Optional
postal_code	String	Optional
state	String	Optional

CheckoutPaymentDto.OrderDetail

Parameters	Data Type
id	String	Optional
price	Double	Optional
name	String	Optional
quantity	Int	Optional
image	String (in the form of web url)	Optional

Response:

Receiving the payment status within the override method onActivityResult is a common practice in integration to handle payment callbacks. By implementing this method during the integration process, developers can capture and process the payment status information returned by the payment gateway or SDK. This allows for real-time feedback on the payment's success or failure, enabling further actions to be taken based on the outcome of the transaction.

---

Possible Error Scenarios:

INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR

1. Ensure that the PortOne Key and Secret Key belong to the same account.
2. Confirm that the Secret Key has not been altered.
3. Verify that the Bearer keyword precedes the generated token with a space. Example: Bearer $jwtToken.
4. Check if the token expiration time is after the current time.

INVALID_UNAUTHORIZED_TRANSACTION_SIGNATURE_ERROR

1. Validate if all parameters align with the payload/request.
2. Ensure that the PortOne key matches with the payload and the account.

INVALID_UNAUTHORIZED_TRANSACTION_IAMPORTKEY_ERROR

1. Confirm that the PortOne key matches with the payload and the account.

INVALID_PAYMENT_CHANNEL

1. Validate that the payment channels and methods included in the payload are enabled in the PortOne portal.

INVALID_ENVIRONMENT

1. Verify that an environment (sandbox or live) has been specified.

Summation of order value, tax, duties, shipping, and discount should equal the total amount

1. If items are provided, ensure that the values match the total amount calculation formula: sum(items price * items quantity) + shipping charge - discount = amount.
2. Mandatory parameters in the payload:
   • price
   • promo_discount (0 accepted)
   • shipping_charges (0 accepted)