Native Android

Android app integration

Introduction

JusPay maintains an official Android SDK to enable you to easily integrate Express Checkout service into your Android application. Please read on for more details.

Getting the SDK

The SDK can be added directly to Gradle based projects by adding the following to the build.gradle:

// Add to build.gradle

repositories {
  mavenCentral()
  maven {
    url 'https://s3-ap-southeast-1.amazonaws.com/jp-build-packages/ec-android-sdk'
  }
  maven {
    url 'https://s3-ap-southeast-1.amazonaws.com/godel-release/godel/'
  }
}

dependencies {
  compile 'in.juspay:ec-android-sdk:1.1.14'
  compile 'com.android.support:support-v4:23.4.0'
}

Note: Android Support V4 library is a required dependency.

Setup Permissions

Our SDK automatically reads the OTP and provides a convenient way for the users to submit the OTPs to complete the transaction. This requires permission to receive/read SMS.

The following are the minimum set of permissions required for the library to work as expected:

<!-- File AndroidManifest.xml-->

<manifest ...>

  <!-- additional permissions -->
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.READ_SMS" />
  <uses-permission android:name="android.permission.RECEIVE_SMS" />
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

  <application>

    <!-- activity declaration -->
    <activity
        android:label="Processing your payment"
        android:name="in.juspay.godel.PaymentActivity"
        android:hardwareAccelerated="true"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="adjustResize"
      >
    </activity>

    <activity
          android:name=".activities.ExpressCheckoutActivity"
          android:hardwareAccelerated="true"
          android:screenOrientation="portrait"
          android:windowSoftInputMode="stateHidden"
          android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
  </application>
</manifest>

Basic Setup

The SDK requires that the merchantId and the environment (Sandbox, production) be configured ahead of time.

This can be done simply by:

Environment.configure(Environment.PRODUCTION, "my-production-mid");

In case your account is configured on sandbox:

Environment.configure(Environment.SANDBOX, "my-sandbox-merchant-id");

MobileWeb Checkout

This mode of checkout opens a mobile optimized web page within the android app to take the payment input from the customer. This is the most straightforward integration. If you wish to disallow certain payment options, you have to explicitly remove the option from the array.

Parameters

Class MobileWebCheckout

Parameter Type Description
orderId String Order ID of the transaction
endUrlRegexes String Array Regex to match the Return URL(s) from JusPay to your website
paymentInstruments PaymentInstrument Array List of options that should be enabled for the customer. If you pass null, then all the options will be made available
// Configure the payment here
MobileWebCheckout checkout = new MobileWebCheckout(
  "orderId",              // The order for which you want to start the payment
  new String[] {
    "https:\\/\\/shop\\.com\\/payment-response.*"
  },
  new PaymentInstrument[] {
    PaymentInstrument.CARD,   // Show the card form
    PaymentInstrument.NB,     // Show the Netbanking choices
    PaymentInstrument.WALLET  // Show Wallet choices
  }
);

checkout.startPayment(
  MyActivity.this,      // Your activity - from where we want to start the checkout
  new BrowserCallback() {     
    @Override
    public void endUrlReached(String url) {
      // Called whenever an endUrl is matched with the URL that is loading in the browser
      // The matched url will be passed
    }

    @Override
    public void ontransactionAborted() {             
      // User pressed back button and confirmed to abort the transaction.
      // Recommended to show the Cart screen with an error message.
    }
  }
);

Core API Checkout

If you have already built screens to accept card & netbanking options, then you can directly use our Java code to initiate a payment with the customers choice.

Create an instance of (Card / NetBanking / Wallet) Payment

Create an instance of the required Payment Object

CardPayment myPayment = new CardPayment();

Now we must configure the payment by setting the required fields. For all payments, the orderId must be set:

myPayment.setOrderId("order-123-20160612");

The merchantId is taken from the Environment which was configured earlier.

For card payments, the following fields must be set:

myPayment
  .setNameOnCard("Cactus Alabactus")
  .setCardNumber("4242424242424242")
  .setCardExpiryDate("12", "2020")
  .setCardSecurityCode("123");

For wallet payments, the wallet brand must be set:

WalletPayment myPayment = new WalletPayment();
myPayment.setWallet("OLAMONEY");

For net banking payments, the bank must be set:

NetbankingPayment myPayment = new NetbankingPayment();
myPayment.setBank("NB_AXIS");

For payments using saved cards, the card token must be set:

SavedCardPayment myPayment = new SavedCardPayment();
myPayment.setCardToken("2d1831c8-39ad-409c-96ad-f3cd67ec9152")
  .setCardSecurityCode("123");

For tokenized card payments where token is not created yet:

CardTokenPayment myPayment = new CardTokenPayment();
myPayment
  .setNameOnCard("Cactus Alabactus")
  .setCardNumber("4242424242424242")
  .setCardExpiryDate("12", "2020")
  .setCardSecurityCode("123");

Tokenizing a saved card, where token is not created yet:

SavedCardTokenPayment myPayment = new SavedCardTokenPayment();
myPayment.setCardToken("2d1831c8-39ad-409c-96ad-f3cd67ec9152")
  .setCardSecurityCode("123");

To generate only the card token, call the ExpressCheckoutService#tokenizeCard API as follows:

int connectTimeout = 1000;
int readTimeout = 2000;

NetUtils nu = new NetUtils(connectTimeout, readTimeout);

CardPayment cardPayment = new CardPayment();
cardPayment
  .setNameOnCard("Cactus Alabactus")
  .setCardNumber("4242424242424242")
  .setCardExpiryDate("12", "2020")
  .setCardSecurityCode("123");
JuspayHttpResponse response = ExpressCheckoutService.tokenizeCard(cardPayment, nu);

To tokenize a saved card, pass in an instance of SavedCardPayment as shown below

int connectTimeout = 1000;
int readTimeout = 2000;

NetUtils nu = new NetUtils(connectTimeout, readTimeout);

SavedCardTokenPayment cardPayment  = new SavedCardTokenPayment();
cardPayment.setCardToken("2d1831c8-39ad-409c-96ad-f3cd67ec9152")
  .setCardSecurityCode("123");

JuspayHttpResponse response = ExpressCheckoutService.tokenizeCard(cardPayment, nu);

The ExpressCheckoutService#tokenizeCard returns an object of type in.juspay.ec.sdk.netutils.JuspayHttpResponse to extract the response token, parse the response body as JSON:

JuspayHttpResponse response = ExpressCheckoutService.tokenizeCard(cardPayment, nu);

// response.responseCode contains the HTTP response code
// response.headers contain the response headers


JSONObject responseBodyJson = new JSONObject(response.responsePayload);

String cardToken = reponseBodyJson.getString("card_token");

In this case the card is tokenized before calling the /txns API.

Start the transaction

Express Checkout SDK integrates with JusPay Safe to offer a seamless payment flow to customers. When the payment is initiated, the authentication URL is handled by the JusPay Safe SDK. See the example code snippet below:

For more details on the in.juspay.juspaysafe.BrowserCallback and in.juspay.juspaysafe.BrowserParams classes, please refer this.

myPayment
.setEndUrls(new String[] {"https:\\/\\/shop\\.com\\/payment-response.*"})
.startPayment(
  MyAndroidActivity.this,
  new BrowserParams(),
  new BrowserCallback() {

    @Override
    public void onWebViewReady(WebView webView) {}

    @Override
    public void onPageStarted(WebView view, String url) {}

    @Override
    public void onEndUrlReached(WebView webView, JSONObject paymentDetail) {
      // Called whenever an endUrl is matched with the URL that is loading in the browser
      // The matched url will be passed
    }

    @Override
    public void onTransactionAborted(JSONObject paymentDetail) {
      // User pressed back button and confirmed to abort the transaction.
      // Recommended to show the Cart screen with an error message.
    }
  },
  new TxnInitListener () {
    @Override
    void beforeInit() {
      // Before calling express checkout backend's /txns API
    };

    @Override
    void onTxnInitResponse(ExpressCheckoutResponse initResponse) {
      // Called after getting response from ExpressCheckout /txns API call
      // This is invoked before the URL returned by the ExpressCheckout backend
      // is loaded into the JuspaySafe browser.
    };

    @Override
    void initError(Exception exception, @Nullable ExpressCheckoutResponse expressCheckoutResponse) {
      // If there was an error in getting the response from the EC backend, like network not
      // being available etc.., this callback is invoked.
    };
  }
);

Helper Methods

GodelAdapter.startBrowser(@NonNull final Activity activity, @NonNull final BrowserCallback browserCallback, @NonNull BrowserParams params)

Helper method to load a URL in the JuspaySafe Browser.

Help & Resources

A sample project demonstrating the various checkout screens can be found here.