Checkout - Android SDK

This document is intended to help understand the integration process of your Android App with Razorpay's Android Checkout SDK.

Note: Due to the recent changes in the Google Play Developer policy, changes have been made in the SMS reading permissions bundled in Razorpay's Android SDK versions 1.5.1 and higher. Therefore, if you are using previous versions of Razorpay's Android SDK, you must upgrade to the latest version available on the Maven Repository.

TLS Changes: According to PCI regulations, payment processing is not allowed on TLS v1. So in case the device does not have TLS v1.1 or TLS v1.2, the SDK will throw an error in the onPaymentError method.

Changelog#

  • UPI related improvements
  • Google SMS policy related updates

Installing the SDK#

You can download the latest versions of the SDK from the Maven Repository.

To add Razorpay's Checkout SDK to your app, add the following dependency in your build.gradle:

repositories { mavenCentral() } dependencies { compile 'com.razorpay:checkout:1.5.1' }

Initializing the SDK#

Add your Razorpay API key to the AndroidManifest.xml:

<!-- Sample AndroidManifest.xml--> <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android"> <application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme" > <activity android:name=".MainActivity" android:label="@string/app_name" > </activity> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> /** */ * Add your API key */ <meta-data android:name="com.razorpay.ApiKey" android:value="YOUR_API_KEY" /> </application> </manifest>

Implementing PaymentResultListener#

To receive callbacks for the payment result, implement the method PaymentResultListener:

Backward Compatibility: All the changes mentioned below are backward compatible. If you want to continue using the older structure, you just need to include the latest SDK through the process mentioned above.

However, it is highly recommended that you refactor your code to support the latest structure. The older methods have been marked as deprecated and will be removed in the next major release.

public class MerchantActivity extends Activity implements PaymentResultListener { // ... @Override public void onPaymentSuccess(String razorpayPaymentID) { /** * Add your logic here for a successful payment response */ } @Override public void onPaymentError(int code, String response) { /** * Add your logic here for a failed payment response */ } }

Your Activity Can Get Recreated: Razorpay's payment process takes place in a new activity. Once the payment is complete, the SDK hands over control to a layer that calls these callback methods. Since there are two activities involved, your activity can get garbage collected / destroyed in case the device is low on memory. Hence, these two methods should not depend on any variable that is not set through your life cycle hooks. Enable the "Don't Keep Activities" option in Developer Options under Settings.

Preload Checkout#

For quick loading of the Checkout form, the preload method of Checkout must be called much earlier than the other methods in the payment flow. The loading time of the preload resources can vary, depending on your network's bandwidth.

public class SomeEarlierMerchantActivity extends Activity { // ... @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); /** * Preload payment resources */ Checkout.preload(getApplicationContext()); // ... } // ... }

Initiating Payments#

To initiate a payment you need to create an instance of Checkout and pass the payment details and options as a JSONObject.

public void startPayment() { /** * Instantiate Checkout */ Checkout checkout = new Checkout(); /** * Set your logo here */ checkout.setImage(R.drawable.logo); /** * Reference to current activity */ final Activity activity = this; /** * Pass your payment options to the Razorpay Checkout as a JSONObject */ try { JSONObject options = new JSONObject(); /** * Merchant Name * eg: ACME Corp || HasGeek etc. */ options.put("name", "Merchant Name"); /** * Description can be anything * eg: Order #123123 * Invoice Payment * etc. */ options.put("description", "Order #123456"); options.put("currency", "INR"); /** * Amount is always passed in PAISE * Eg: "500" = Rs 5.00 */ options.put("amount", "500"); checkout.open(activity, options); } catch(Exception e) { Log.e(TAG, "Error in starting Razorpay Checkout", e); } }

Checkout.open() launches the Checkout form where the user completes the payment and returns the payment result via appropriate callbacks on the PaymentResultListener.

Payment Options in JSONObject:

All available options in the checkout.js are also available in android. Refer this list to know about the allowed options.

Implementation details when using Fragment: If you are calling the payment start method from inside a fragment, ensure that the fragment's parent activity implements the PaymentResultListener interface.

Error codes#

The error codes that are returned in the onPaymentError method are:

Error_Code

Description

Checkout.NETWORK_ERROR

There was a network error, for example loss of internet connectivity

Checkout.INVALID_OPTIONS

An issue with options passed in checkout.open

Checkout.PAYMENT_CANCELED

User cancelled the payment

Checkout.TLS_ERROR

Device does not support TLS v1.1 or TLS v1.2

Override the minimum API level#

This version of Checkout Android SDK is compatible with Android version "19" or higher. Therefore, your app should support Android version 19 or higher. Nonetheless, if you want to use versions lower than 19.0 in your app, you can override the minimum value of the SDK version as shown below:

<uses-sdk android:targetSdkVersion="27" android:minSdkVersion="14" tools:overrideLibrary="com.razorpay"/>

Customization Options#

You can customize the checkout form to suit your organization as shown below:

Adding the Company Logo#

By default, the Checkout form uses the logo specified on the Dashboard. You can also set a custom logo in the Checkout form. For this you need to call the following method before you call open method.

int image = R.drawable.logo; // Can be any drawable checkout.setImage(image);

If you pass both, image in options as well as through this method, the image from drawables is picked up.

Disabling Checkout in Full screen#

The Checkout form runs in a separate activity. This activity picks up the theme from the Manifest file. So if you have a full screen theme, even the Checkout will run in full screen. It is suggested to disable the Checkout in full screen mode to enable the user to switch between various apps, for example, while entering the OTP.

If your app is in a full screen mode, you can disable it for Checkout by calling the following method:

checkout.setFullScreenDisable(true)

Erase User Data from SDK#

The SDK stores specific data of the user such as email, contact number, and user-session cookies, in case the user wants to make another payment in the same session. You might want to delete the sensitive information before another user logs into the app.

To erase user data from the app, you can call the following method anywhere in your app.

Checkout.clearUserData(Context)

Proguard rules#

If you are using Proguard for your builds, modify the build file:

-keepclassmembers class * { @android.webkit.JavascriptInterface <methods>; } -keepattributes JavascriptInterface -keepattributes *Annotation* -dontwarn com.razorpay.** -keep class com.razorpay.** {*;} -optimizations !method/inlining/* -keepclasseswithmembers class * { public void onPayment*(...); }

Note: You can get in touch with us at https://razorpay.com/support for any queries.