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.

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

1. Install PortOne Android SDK and Authorise it.#

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

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. Initialize the `PortOne` Instance:#

Create an instance of the PortOne SDK in the activity where the payment checkout process occurs.
Initialize 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:

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

JWT Token Construction:
Implement the server-side logic to generate a JWT token using the portoneKey as a key component of the token payload.
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 Connect#

Android Connect SDK empowers merchants with advanced business logic functionalities, focusing solely on core processing capabilities without the inclusion of pre-built user interface components. This design choice offers flexibility to merchants, allowing them the freedom to craft and customize their own unique checkout interface tailored to their brand aesthetics and user experience preferences.

The Android Connect SDK provides a detailed breakdown of key functionalities essential for merchants to enhance their payment processing capabilities efficiently. Each point represents a specific feature or action that can be easily referenced for seamless integration and utilization within merchant applications.

Overview:#

Fetch Enabled Payment Methods and Channels
Checkout Using a New Credit/Debit Card
Checkout Using Saved Credit/Debit Cards
1. Retrieve Saved Cards Using Phone Number
  1. Fetch OTP for Authentication
  2. Fetch Saved Cards Using Phone Number and OTP
2. Retrieve Saved Cards Using Auth Token
Checkout Using Non-Tokenized Methods
1. Instalments
2. Direct Bank Transfer
Merchant Centric Card Vault
1. Create a Customer
2. Save a Card for Customer
3. Fetch a List of Cards for a Customer
4. Delete Card for a Customer
PreAuth and Capture
Failover Routing

The subsequent methods are elaborated upon extensively, including their practical applications:

This method is utilized to retrieve the available payment channels and methods that can be used for the checkout process.
Parameters Data Type
portoneKey String mandatory
subMerchantKey String Optional
currency String mandatory
portOne.getPaymentMethods(
portoneKey = portoneKey,
subMerchantKey = subMerchantKey,
currency = currency,
object :
ApiCallbackInterface<PaymentDto.PaymentMethodResponse> {
override fun onSucceed(response: PaymentDto.PaymentMethodResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}
})

This method is employed to initiate the checkout process with a new card, allowing for payment from a card that has not been saved previously.

portOne.checkoutUsingNewCard(
                paymentDetails = PaymentDto.CheckoutUsingTokenizationRequest(),
                newCard = PaymentDto.NewCard(),
                token = jwtToken,
            )

`jwtToken`#

The jwtToken serves as the authentication mechanism in the API, generated following the guidelines outlined in the integration documentation.

`PaymentDto.NewCard`#

Parameters	Data Type
cardNumber	String	mandatory
cardType	String	mandatory
cardholderName	String	mandatory
serviceCode	String	mandatory
expiryYear	String	mandatory
expiryMonth	String	mandatory
environment	String	mandatory
portoneKey	String	mandatory

`PaymentDto.CheckoutUsingTokenizationRequest`#

Parameters	Data Type
portoneKey	String	mandatory
paymentChannel	String	mandatory
paymentMethod	String	mandatory
merchantOrderId	String	mandatory
amount	Double	mandatory
currency	String	mandatory
billingDetails	CheckoutPaymentDto.BillingDetails	Optional
shippingDetails	CheckoutPaymentDto.ShippingDetails	Optional
orderDetails	List< CheckoutPaymentDto.OrderDetail>	Optional
successUrl	String	mandatory
failureUrl	String	mandatory
environment	String	mandatory
redirectUrl	String	mandatory
description	String	Optional
source	String	mandatory
transactionType	String	mandatory

To make a payment using saved cards for the first time, the following method facilitates fetching the cards linked to the phone number. However, to access the cards, OTP authentication is necessary, requiring a two-step process.
1. Retrieving the saved cards for the initial occurrence.
  1. This method is employed to send an OTP to the registered phone number.
    Parameters Data Type
    phoneNo String mandatory
    portOne.getOTP(phoneNo = phoneNo, object :
    ApiCallbackInterface<PaymentDto.OtpResponse> {
    override fun onSucceed(response: PaymentDto.OtpResponse) {
    LoggerUtil.info("Successful")
    }
    
    override fun onFailure(
    errorCode: Int?,
    status: String?,
    errorMessage: String,
    throwable: Throwable
    ) {
    LoggerUtil.info("Failed")
    }
    })
  2. Upon completing the previous step, an OTP will be sent to the phone number, serving as the input for subsequent authentication.
    Parameters Data Type
    token String Optional
    portoneKey String mandatory
    phoneNo String mandatory
    otp String mandatory
    portOne.getSavedCards(
    token = null,
    portoneKey = portoneKey,
    phoneNo = phoneNo,
    otp = otp,
    object :
    ApiCallbackInterface<PaymentDto.CreditCardDetailsResponse> {
    override fun onSucceed(response: PaymentDto.CreditCardDetailsResponse) {
    LoggerUtil.info("Successful")
    }
    
    override fun onFailure(
    errorCode: Int?,
    status: String?,
    errorMessage: String,
    throwable: Throwable
    ) {
    LoggerUtil.info("Failed")
    }
    })
2. Retrieving the saved cards repeatedly. Following the initial retrieval of saved cards, a token is obtained in the response, offering an alternative method for authentication. This token can be utilised in place of the OTP, providing convenience for subsequent card retrievals.
  | Parameters | Data Type | |
  | --- | --- | --- |
  | token | String | mandatory |
  | portoneKey | String | mandatory |
  | phoneNo | String | mandatory |
  | otp | String | Optional |
  
```kotlin
portOne.getSavedCards(
token = token,
portoneKey = portoneKey,
phoneNo = phoneNo,
otp = null,
object :
ApiCallbackInterface<PaymentDto.CreditCardDetailsResponse> {
override fun onSucceed(response: PaymentDto.CreditCardDetailsResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}
})
```

Parameters	Data Type
phoneNo	String	mandatory

Parameters	Data Type
token	String	Optional
portoneKey	String	mandatory
phoneNo	String	mandatory
otp	String	mandatory

The following method is utilized for processing non-tokenized payment methods, where tokenization is not required for transaction completion. This method facilitates streamlined checkout experiences for payment methods that do not necessitate the tokenization process.

portOne.checkoutWithoutTokenization(
                request = PaymentDto.CheckoutWithoutTokenizationReques()
            )

For the non-tokenized flow, it is necessary to pass an object containing the checkout request details to facilitate the payment process without requiring tokenization.

`PaymentDto.CheckoutWithoutTokenizationRequest`#

Parameters	Data Type
portoneKey	String	mandatory
paymentChannel	String	mandatory
paymentMethod	String	mandatory
merchantOrderId	String	mandatory
amount	Double	mandatory
currency	String	mandatory
billingDetails	CheckoutPaymentDto.BillingDetails	Optional
shippingDetails	CheckoutPaymentDto.ShippingDetails	Optional
orderDetails	List< CheckoutPaymentDto.OrderDetail>	Optional
successUrl	String	mandatory
failureUrl	String	mandatory
environment	String	mandatory
redirectUrl	String	mandatory
description	String	Optional
source	String	mandatory
transactionType	String	mandatory

The parameters mentioned above are standard for non-tokenized checkout methods. However, additional parameters and steps are required for specific methods such as Direct Bank Transfer and Instalments.

These methods also fall under the non-tokenized flow but necessitate extra parameters and steps in the request process.

Direct Bank Transfer
Instalments

These methods, while classified under non-tokenized flows, entail supplementary parameters and steps in the request, as outlined in detail below.

Direct Bank Transfer#

To process a Direct Bank Transfer checkout, the following steps should be followed:

Fetch Direct Bank Transfer Details: Utilise the following method that only requires the portoneKey as input to retrieve the details pertaining to Direct Bank Transfer.
```kotlin
portOne.getDBTDetails(portoneKey = portoneKey,
object : ApiCallbackInterface<PaymentDto.DBTResponse> {
override fun onSucceed(response: PaymentDto.DBTResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}

})
```

Process Checkout with Bank Details: Once the bank details are obtained, incorporate them into the payload for checkout processing.
```kotlin
portOne.checkoutUsingDirectBankTransfer(
PaymentDto.CheckoutWithDirectBankTransferRequest()
)
```

The upcoming request mirrors the structure of the checkout request object without tokenization, with the exception of the final additional object appended to the request.

### `PaymentDto.CheckoutWithDirectBankTransferRequest()`

| Parameters | Data Type | |
| --- | --- | --- |
| portoneKey | String | mandatory |
| paymentChannel | String | mandatory |
| paymentMethod | String | mandatory |
| merchantOrderId | String | mandatory |
| amount | Double | mandatory |
| currency | String | mandatory |
| billingDetails | CheckoutPaymentDto.BillingDetails | Optional |
| shippingDetails | CheckoutPaymentDto.ShippingDetails | Optional |
| orderDetails | List< CheckoutPaymentDto.OrderDetail> | Optional |
| successUrl | String | mandatory |
| failureUrl | String | mandatory |
| environment | String | mandatory |
| redirectUrl | String | mandatory |
| description | String | Optional |
| source | String | mandatory |
| transactionType | String | mandatory |
| DBTDetails | PaymentDto.DBTDetails | mandatory |

### `PaymentDto.DBTDetails`

| Parameters | Data Type | |
| --- | --- | --- |
| customerName | String | mandatory |
| transactionTime | String | mandatory |
| amountPaid | Double | mandatory |

Instalments#

To initiate an Instalments checkout, the following steps need to be taken:

Retrieve Bank List for Instalments: Initially, fetching the bank list that offers instalment options is necessary to process instalment payments.
```kotlin
portOne.getBankList(
channel = paymentChannel,
request = PaymentDto.BankListRequest(),
object : ApiCallbackInterface<PaymentDto.BankListResponse> {
override fun onSucceed(response: PaymentDto.BankListResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}

})
```

### `PaymentDto.BankListRequest()`

| Parameters | Data Type | |
| --- | --- | --- |
| amount | Double | mandatory |
| environment | String | mandatory |
| portoneKey | String | mandatory |
| isMerchantSponsored | Boolean | mandatory |
| paymentMethod | String | mandatory |
| overrideDefault | Boolean | mandatory |
| currency | String | mandatory |

The response will include a list of banks and associated terms which must be included in the request body for further processing.

Request Parameters for Instalments:

The subsequent request parameters are consistent with the generic checkout request object without tokenization, apart from the addition of a supplementary object for Instalments.

portOne.checkoutUsingInstallation(
                PaymentDto.CheckoutWithInstallationRequest()
            )

`PaymentDto.CheckoutWithInstallationRequest()`#

Parameters	Data Type
portoneKey	String	mandatory
paymentChannel	String	mandatory
paymentMethod	String	mandatory
merchantOrderId	String	mandatory
amount	Double	mandatory
currency	String	mandatory
billingDetails	CheckoutPaymentDto.BillingDetails	Optional
shippingDetails	CheckoutPaymentDto.ShippingDetails	Optional
orderDetails	List< CheckoutPaymentDto.OrderDetail>	Optional
successUrl	String	mandatory
failureUrl	String	mandatory
environment	String	mandatory
redirectUrl	String	mandatory
description	String	Optional
source	String	mandatory
transactionType	String	mandatory
bankDetails	PaymentDto.BankDetails	mandatory

`PaymentDto.BankDetails`#

Parameters	Data Type
bankCode	String	mandatory
bankName	String	mandatory
isMerchantSponsored	Boolean	mandatory
overrideDefault	Boolean	mandatory
installmentPeriod	PaymentDto.TermObject	mandatory

`PaymentDto.TermObject`#

Parameters	Data Type
month	Int	mandatory

For non-tokenized methods such as Direct Bank Transfer and Installments, the method for receiving the response is already included during integration, which is the payment status listener.

Merchant Centric Card Vault#

The Merchant Centric Card Vault operates by enrolling merchants initially, followed by adding customers specific to each merchant. Cards are then saved based on individual customers, ensuring a personalized and secure card storage system. Several methods are available to facilitate various operations within this card vault setup.

The subsequent method is utilised for customer addition.
portOne.addCustomer(
token = token,
portOneKey = portoneKey,
subMerchantKey = subMerchantKey,
request = PaymentDto.AddCustomerRequest(
name = name,
phoneNo = phoneNo,
email = email,
customerRef = customerRef
),
object : ApiCallbackInterface<PaymentDto.AddCustomerResponse> {
override fun onSucceed(response: PaymentDto.AddCustomerResponse) {
val gson = Gson()
val json = gson.toJson(response)
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}

})
Parameters Data Type
token String mandatory
portoneKey String mandatory
subMerchantKey String Optional
name String mandatory
phoneNo String mandatory
email String mandatory
customerRef String mandatory

Parameters	Data Type
token	String	mandatory
portoneKey	String	mandatory
subMerchantKey	String	Optional
name	String	mandatory
phoneNo	String	mandatory
email	String	mandatory
customerRef	String	mandatory

The following method is used to save a particular card for a specific customer.

portOne.addCardForCustomer(
                customerUUID = customerUUID,
                token = token,
                portoneKey = portoneKey,
                subMerchantKey = subMerchantKey,
                request = PaymentDto.NewCard(),
                object : ApiCallbackInterface<PaymentDto.AddCardsResponse> {
                    override fun onSucceed(response: PaymentDto.AddCardsResponse) {
                        LoggerUtil.info("Successful")
                    }

                    override fun onFailure(
                        errorCode: Int?,
                        status: String?,
                        errorMessage: String,
                        throwable: Throwable
                    ) {
                        LoggerUtil.info("Failed")
                    }

                })

Parameters	Data Type
customerUUID	String	mandatory
token	String	mandatory
portoneKey	String	mandatory
subMerchantKey	String	Optional

`PaymentDto.NewCard`#

Parameters	Data Type
cardNumber	String	mandatory
cardType	String	mandatory
cardholderName	String	mandatory
serviceCode	String	mandatory
expiryYear	String	mandatory
expiryMonth	String	mandatory
environment	String	mandatory
portoneKey	String	mandatory

This method is utilized to retrieve the stored cards based on the customer.
portOne.listCardsForCustomer(
customerUUID = customerUUID,
token = token,
portoneKey = portoneKey,
subMerchantKey = subMerchantKey,
object : ApiCallbackInterface<PaymentDto.ListCardsForCustomerResponse> {
override fun onSucceed(response: PaymentDto.ListCardsForCustomerResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}

})
Parameters Data Type
customerUUID String mandatory
token String mandatory
portoneKey String mandatory
subMerchantKey String Optional
This method is employed to remove a specific card for an individual customer.
portOne.deleteCardForCustomer(
customerUUID = customerUUID,
token = token,
portoneKey = portoneKey,
subMerchantKey = subMerchantKey,
request = PaymentDto.DeleteCardRequest(token = cardToken),
object : ApiCallbackInterface<PaymentDto.GenericResponse> {
override fun onSucceed(response: PaymentDto.GenericResponse) {
LoggerUtil.info("Successful")
}

override fun onFailure(
errorCode: Int?,
status: String?,
errorMessage: String,
throwable: Throwable
) {
LoggerUtil.info("Failed")
}

})

Parameters Data Type
customerUUID String mandatory
token String mandatory
portoneKey String mandatory
subMerchantKey String Optional
Parameters Data Type Remarks
cardToken String mandatory The Card Token can be retrieved in the above fetching the list of cards method

Parameters	Data Type		Remarks
cardToken	String	mandatory	The Card Token can be retrieved in the above fetching the list of cards method

Pre-authorization and Payment Capture#

During Pre-authorization, the transaction is initially approved, and at a later time or within specified days, the payment can be processed using the Capture API.

To designate a transaction for pre-authorization, a specific parameter must be configured in the payload:

transactionType = *PREAUTH*

    val paymentDetails= PaymentDto.CheckoutUsingTokenizationRequest()
    paymentDetails.transactionType= "PREAUTH"

Following the pre-authorization of a transaction, the subsequent method is utilized for capturing the transaction.

portOne.captureTransaction(
                orderReference = orderReference,
                portoneKey = portoneKey,
                token = token,
                object : ApiCallbackInterface<PaymentDto.GenericResponse> {
                    override fun onSucceed(response: PaymentDto.GenericResponse) {
                        LoggerUtil.info("Successful")
                    }

                    override fun onFailure(
                        errorCode: Int?,
                        status: String?,
                        errorMessage: String,
                        throwable: Throwable
                    ) {
                        LoggerUtil.info("Failed")
                    }

                })

Parameters	Data Type
orderReference	String	mandatory
portoneKey	String	mandatory
token	String	mandatory

Failover Routing#

Failover routing is a functionality designed to ensure seamless credit card payment processing. This feature allows the configuration of primary and secondary payment channels through the admin portal. If a payment attempt using the primary channel fails for any reason, the system automatically redirects the user to the secondary payment channel.

Following method is used to fetch routes created in admin portal.

portOne.getRoutesList(
                token = token,
                portoneKey = portoneKey,
                object : ApiCallbackInterface<PaymentDto.RoutesListResponse> {
                    override fun onSucceed(response: PaymentDto.RoutesListResponse) {
                        val gson = Gson()
                        val json = gson.toJson(response)
                        LoggerUtil.info("Successful")
                    }

                    override fun onFailure(
                        errorCode: Int?,
                        status: String?,
                        errorMessage: String,
                        throwable: Throwable
                    ) {
                        LoggerUtil.info("Failed")
                    }

                })

This method provides the routeRef that should be included in the payload as outlined below:

Enable routing by setting isRoutingEnabled to true.
Specify the Routing Param type as failover.
Include the Routing Ref, which is configured in the merchant portal.

    val paymentDetails = PaymentDto.CheckoutUsingTokenizationRequest()
    paymentDetails.isRoutingEnabled= true     // true || false
    paymentDetails.routingParams= PaymentDto.RoutingParams(type = "failover", routeRef)

Possible Error Scenarios:#

`INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR`#

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

`INVALID_UNAUTHORIZED_TRANSACTION_SIGNATURE_ERROR`#

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

`INVALID_UNAUTHORIZED_TRANSACTION_IAMPORTKEY_ERROR`#

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

`INVALID_PAYMENT_CHANNEL`#

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

`INVALID_ENVIRONMENT`#

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

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

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

Video Tutorial#

Part-1: Installation of Android Native SDK#

Part 2: Initialising the SDK and Setting Intent Filters#

Sample App#

Prerequisites#

Integration#

1. Install PortOne Android SDK and Authorise it.#

2. Initialize the PortOne Instance:#

3. Set the Intent Filters in the Manifests#

4. Set Intent Receivers for Payment Status:#

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

Android Connect#

Overview:#

jwtToken#

PaymentDto.NewCard#

PaymentDto.CheckoutUsingTokenizationRequest#

PaymentDto.CheckoutWithoutTokenizationRequest#

Direct Bank Transfer#

Instalments#

PaymentDto.CheckoutWithInstallationRequest()#

PaymentDto.BankDetails#

PaymentDto.TermObject#

Merchant Centric Card Vault#

PaymentDto.NewCard#

Pre-authorization and Payment Capture#

Failover Routing#

Possible Error Scenarios:#

INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR#

INVALID_UNAUTHORIZED_TRANSACTION_SIGNATURE_ERROR#

INVALID_UNAUTHORIZED_TRANSACTION_IAMPORTKEY_ERROR#

INVALID_PAYMENT_CHANNEL#

INVALID_ENVIRONMENT#

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

2. Initialize the `PortOne` Instance:#

`jwtToken`#

`PaymentDto.NewCard`#

`PaymentDto.CheckoutUsingTokenizationRequest`#

`PaymentDto.CheckoutWithoutTokenizationRequest`#

`PaymentDto.CheckoutWithInstallationRequest()`#

`PaymentDto.BankDetails`#

`PaymentDto.TermObject`#

`PaymentDto.NewCard`#

`INVALID_UNAUTHORIZED_JWT_TOKEN_ERROR`#

`INVALID_UNAUTHORIZED_TRANSACTION_SIGNATURE_ERROR`#

`INVALID_UNAUTHORIZED_TRANSACTION_IAMPORTKEY_ERROR`#

`INVALID_PAYMENT_CHANNEL`#

`INVALID_ENVIRONMENT`#

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