Android

Integrate the Nimbbl Android SDK with your android app and start accepting payments from your customers.

SAMPLE EXPERIENCE

• You can refer to the Nimbbl sample app to learn how the SDK has been integrated.
• Nimbbl Android Sample App

Compatibilities and Dependencies

1. The minsdk for your app should target Android version 22+ (API level 22)
2. Target SDK version 36+ (API level 36) is recommended

Install the Nimbbl Android SDK

To add the SDK to your app, add following change in app/build.gradle file:

dependencies {
    implementation 'com.github.nimbbl-tech:nimbbl_mobile_kit_android_webview_sdk:v4.0.9'
}

Changes in project build.gradle

repositories {
    maven { url 'https://jitpack.io' }
}

Initialise the Nimbbl Android SDK

You can choose to do this on app launch or any other point before you will be invoking the checkout

Kotlin

NimbblCheckoutSDK.getInstance().init(this)

Java

NimbblCheckoutSDK.getInstance().init(this)

Launching the Checkout

Understanding Checkout Options

Nimbbl lets you enforce a payment mode on the Checkout. This can be done by setting up the setPaymentModeCode property. There are other related properties in to each different payment mode, you can read it in the table below. If you don't set setPaymentModeCode the customer is shown the full Checkout with all available payment modes.

Option Properties	Type	Mandatory?	Description
setOrderToken	string	true	This would have been generated from your server during order creation using V3 create-order API.
setPaymentModeCode	string	false	In case of specific payment mode, this property is mandatory. Possible values net_banking, card, upi, wallet, emi. If you don't pass payment_mode_code the customer is shown the full Checkout with all available payment modes.
setBankCode	string	false	Only to be passed in case of net_banking. Example: hdfc. To get the full list of banks supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their bank from enabled banks
setWalletCode	string	false	Only to be passed in case of wallet. Example: jio_money. To get the full list of wallets supported for you, please use this API. If it isn't passed, Checkout will open with a page for the user to choose their wallet from enabled wallets
setPaymentFlow	string	false	Only to be passed in case of upi to determine the flow. Possible value is intent. If it isn't passed, Checkout will open with page for the user to pay using a QR or choose a UPI app
setEmiCode	string	false	Only to be passed in case of emi. Possible values debit, credit, cardless. If it isn't passed, Checkout will show all available EMI options

Setting the Checkout Options

Kotlin

val options = builder.setOrderToken(<orderToken | mandatory>)
                    // only if you want to enforce a specific payment mode
                    .setPaymentModeCode(<string | optional>)
                    .setBankCode(<string | optional>)
                    .setPaymentFlow(<string | optional>)
                    .setWalletCode(<string | optional>)
                    .setEmiCode(<string | optional>)
                    .build()

Java

NimbblCheckoutOptions options = builder.setOrderToken(<orderToken | mandatory>)
                        // only if you want to enforce a specific payment mode
                         .setPaymentModeCode(<string | optional>)
                         .setBankCode(<string | optional>)
                         .setPaymentFlow(<string | optional>)
                         .setWalletCode(<string | optional>)
                         .setEmiCode(<string | optional>)
                         .build();

Invoking the Checkout

Kotlin

    val builder = NimbblCheckoutOptions.Builder()
    NimbblCheckoutSDK.instance?.checkout(options)

Java

    NimbblCheckoutOptions.Builder builder = new NimbblCheckoutOptions.Builder();
    if (NimbblCheckoutSDK.getInstance() != null) {
        NimbblCheckoutSDK.getInstance().checkout(options);
    }

INFO

• You will need to get your app package name whitelisted by our team.
• Please drop an email to [email protected] to get this whitelisting done.

Capture Transaction Response

You have to implement NimbblCheckoutPaymentListener to receive callbacks for the payment result.

Kotlin

import tech.nimbbl.webviewsdk.models.interfaces.NimbblCheckoutPaymentListener

class CatalogPage : AppCompatActivity(), NimbblCheckoutPaymentListener  {

    override fun onCheckoutResponse(data: MutableMap<String, Any>) {
        // Handle payment response
        val status = data["status"]?.toString()
        val orderId = data["order_id"]?.toString()
        val transactionId = data["transaction_id"]?.toString()
        
        when (status?.lowercase()) {
            "success" -> {
                // Payment successful
            }
            "failed" -> {
                // Payment failed
            }
            "cancelled" -> {
                // Payment cancelled
            }
        }
    }
}

Java

import tech.nimbbl.webviewsdk.models.interfaces.NimbblCheckoutPaymentListener;

class CatalogPage extends AppCompatActivity implements NimbblCheckoutPaymentListener  {
    
    @Override
    public void onCheckoutResponse(Map<String, Object> data) {
        // Handle payment response
        String status = (String) data.get("status");
        String orderId = (String) data.get("order_id");
        String transactionId = (String) data.get("transaction_id");
        
        if ("success".equalsIgnoreCase(status)) {
            // Payment successful
        } else if ("failed".equalsIgnoreCase(status)) {
            // Payment failed
        } else if ("cancelled".equalsIgnoreCase(status)) {
            // Payment cancelled
        }
    }
}

A successful payment returns response to the Checkout Form, for details related to processing response check Completing the Integration.

IMPORTANT

• Share the response parameters received to your server
• This will need to be validated on your server before you decide to provide goods or services
• More details available on processing the response in Completing the Integration

Migration Guide for SDK v4.x.x

If you're upgrading from SDK version 3.x.x or earlier, follow this migration guide:

1. Update Dependencies

Before (v3.x.x)

dependencies {
    implementation 'com.github.nimbbl-tech:nimbbl_mobile_kit_android_webview_sdk:3.0.12'
}

After (v4.x.x)

dependencies {
    implementation 'com.github.nimbbl-tech:nimbbl_mobile_kit_android_webview_sdk:v4.0.9'
}

2. Update Payment Listener Interface

Before (v3.x.x)

class MyActivity implements NimbblCheckoutPaymentListener {
    @Override
    public void onPaymentSuccess(Map<String, Object> data) {
        // Handle success
    }
    
    @Override
    public void onPaymentFailed(String data) {
        // Handle failure
    }
}

After (v4.x.x)

class MyActivity implements NimbblCheckoutPaymentListener {
    @Override
    public void onCheckoutResponse(Map<String, Object> data) {
        String status = (String) data.get("status");
        if ("success".equalsIgnoreCase(status)) {
            // Handle success
        } else if ("failed".equalsIgnoreCase(status)) {
            // Handle failure
        }
    }
}

3. Breaking Changes

1. Payment Listener: The onPaymentSuccess and onPaymentFailed methods have been replaced with a single onCheckoutResponse method.

2. Package Structure: All classes have moved to the tech.nimbbl.webviewsdk package.

4. Testing Your Migration

1. Update your dependencies and repository configuration
2. Replace the payment listener implementation
3. Test the integration thoroughly in your development environment

Migration Note

Make sure to test your integration thoroughly after migration. The new SDK version includes enhanced error handling and improved response structure.

For SDK Version 3.x.x and Earlier

If you're using SDK version 3.x.x or earlier and want to continue with the existing implementation, follow the instructions below:

Installation for v3.x.x

dependencies {
    implementation 'com.github.nimbbl-tech:nimbbl_mobile_kit_android_webview_sdk:3.0.12'
}

Repository Configuration:

repositories {
    maven { url 'https://jitpack.io' }
}

Initialization for v3.x.x

Kotlin

NimbblCheckoutSDK.instance?.init(this)

Java

NimbblCheckoutSDK.getInstance().init(this)

Payment Listener for v3.x.x

Kotlin

class CatalogPage : AppCompatActivity(), NimbblCheckoutPaymentListener  {

    override fun onPaymentFailed(data: String) {
        // Handle payment failure
    }

    override fun onPaymentSuccess(data: MutableMap<String, Any>?) {
        // Handle payment success
    }
}

Java

class CatalogPage extends AppCompatActivity implements NimbblCheckoutPaymentListener  {
    @Override
    public void onPaymentFailed(String data) {
        // Handle payment failure
    }

    @Override
    public void onPaymentSuccess(Map<String, Object> data) {
        // Handle payment success
    }
}

Checkout Options for v3.x.x

Kotlin

val builder = NimbblCheckoutOptions.Builder()
val options = builder.setOrderToken(<orderToken | mandatory>)
                    .setPaymentModeCode(<string | optional>)
                    .setBankCode(<string | optional>)
                    .setPaymentFlow(<string | optional>)
                    .setWalletCode(<string | optional>)
                    .setEmiCode(<string | optional>)
                    .build()

NimbblCheckoutSDK.instance?.checkout(options)

Java

NimbblCheckoutOptions.Builder builder = new NimbblCheckoutOptions.Builder();
NimbblCheckoutOptions options = builder.setOrderToken(<orderToken | mandatory>)
                        .setPaymentModeCode(<string | optional>)
                        .setBankCode(<string | optional>)
                        .setPaymentFlow(<string | optional>)
                        .setWalletCode(<string | optional>)
                        .setEmiCode(<string | optional>)
                        .build();

if (NimbblCheckoutSDK.getInstance() != null) {
    NimbblCheckoutSDK.getInstance().checkout(options);
}

Legacy Support Note

SDK version 3.x.x is maintained for backward compatibility but will not receive new features or major updates. We recommend upgrading to v4.x.x for the latest features, security updates, and improved performance.

Related Reading

Creating an OrderRequired server-side configurationStandard Checkout OverviewIntegration overviewSonic Product OverviewWhat customers see