The PortOne Android SDK simplifies the integration of the PortOne Payment Gateway into your Android app, offering a secure, reliable, and efficient way to accept payments. With this SDK, you can seamlessly embed your app to a variety of payment channels, providing a smooth payment experience for users

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:

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.
• Android application for the integration:
  You will need an existing Android application in which you intend to integrate the PortOne Android SDK for payment processing capabilities.
• 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 ** [email protected]

Integration

Steps to integrate your Android application with PortOne Android SDK.

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

1. Install PortOne Android SDK and Authorise it.

To begin, add the PortOne Android SDK to your project by adding the dependency to your build.gradle file.

• In the build.gradle (:app) file, add:

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

• Next, add the authKey to your gradle.properties file:.

authKey= XXXXXXXXXXXXXXXXXXXXXX

• Authorize the SDK by adding the provided authKey to your gradle.properties file, which you can request by emailing the PortOne team at [email protected].

Then, configure your build.gradle (:Project) or settings.gradle to reference the key:

1. Build.gradle (:Project) Setup:

   Kotlin

   repositories {
           maven { url '<https://maven.google.com/>' }
           maven{
               url '<https://jitpack.io>'
               credentials { username authKey }
           }
       }
   

2. Settings.gradle Setup:

   Kotlin

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

Include the necessary code in your build.gradle () file, specifying the project dependency and Kotlin version.

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. Set the Intent Filters in the Manifests

• Next, you need to add intent filters in your AndroidManifest.xml to handle payment status updates and navigate users back to your app after payment.

  XML

  <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>
  
  

This setup ensures your app can handle the redirection URL after payment completion. For detailed instructions, refer to the deep linking guide here.

3. Set Intent Receivers for Payment Status:

You’ll need to handle the payment status response using the onActivityResult method. Here’s an example:.

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
                }

            }

        }
    }

This method receives the payment status and updates the user interface with the payment result.

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

The PortOne SDK requires a JWT token for authentication. You need to implement a server-side process to generate this token and retrieve it in your Android app.

Steps:

1. Implement server logic to generate a JWT token.
2. In your Android app, fetch the token to process the checkout.

The process for generating a JWT token can be found in detail here

5. Generate Signture Hash

To generate a signature hash, create it on the server side using a secret key that will be included in the payload. This ensures secure processing of transactions.

Steps:

1. Implement server logic to generate a signature hash.
2. In your Android app, fetch the signature hash to process the checkout.

The process for generating a Signature Hash can be found in detail here

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

Implementation

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

val checkoutDetails = CheckoutPaymentDto.CheckoutUsingWebRequest()
portone.checkoutUsingWeb(
            token = getJwtToken(clientKey),
            clientKey = clientKey,
            request = checkoutDetails
        )

CheckoutPaymentDto.CheckoutUsingWebRequest

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

CheckoutPaymentDto.MerchantDetails

CheckoutPaymentDto.BillingDetails

CheckoutPaymentDto.ShippingDetails

CheckoutPaymentDto.Address

CheckoutPaymentDto.OrderDetail

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)