Start the browser

Instantiate BrowserCallback

Callback which will be invoked when a user completes the payment or cancels it midway. Whenever a payment is completed (successfully or not), the aggregator/gateway will send the user back to your website. Usually, you would pass single return_url or multiple URLs to aggregator to represent success, failure or cancel.

ontransactionAborted(JSONObject paymentDetails)

Method ontransactionAborted is invoked when the user clicks back button in the payment flow. We assume that the intent of the user is to cancel the transaction. A detailed information of the session is passed in the JSONObject parameter.

endUrlReached(JSONObject paymentDetails)

Method endUrlReached is invoked when we encounter a URL which is identified by you as a return URL or the last URL in the payment flow. The matched URL will be passed in the url key of the JSONObject parameter.

JusPay Browser expects endUrlRegexes as an input. This variable represents an array of String which are regular expressions to match the final return URL. You can send as many URLs as you want here. If the return flow (from gateway to merchant) uses HTTP GET, shouldOverrideUrlLoading is used to check if the URL matches the regex and in case of POST, onPageStarted method will evaluate the regex. If matched, then endUrlReached is invoked by the browser. You will now have control of the user session.

public BrowserCallback callBack = new BrowserCallback() {

  public void ontransactionAborted(JSONObject paymentDetails) {
    Toast.makeText(context,  "Transaction cancelled.", Toast.LENGTH_LONG).show();
    // Payment was not completed by the user. So, lets present the retry option to the user.

  public void endUrlReached(JSONObject paymentDetails) {
    // Required action performed
    Toast.makeText(context, "Transaction completed. Maybe failure/success.", Toast.LENGTH_LONG).show();
    // Payment step has been completed by the user. Take the user to the next step.


If your aggregator uses HTTP GET to redirect the user to you, then the last URL will never hit your server. However, if HTTP POST is used, then the URL will hit your server (with POST parameters).

Deprecation Notice:

ontransactionAborted() and endUrlReached(String url) are now deprecated in favour of the above methods.

paymentDetails JSON Object

paymentDetails json object provides a list of attributes to understand session of the payment. This object is passed via the ontransactionAborted method and endUrlReached method of BrowserCallback interface

Find below the set of parameters which will be sent:

Variable Description Type Example
inferred_payment_status Overall payment Status inferred by Juspay Safe String SUCCESS
payment_statuses Payment status details inferred stage-wise JSON
dropout_reasons Has a Json Object that has the user dropout reason JSON
  "dropoutReason":["User Aborted"],
url* The url at which transaction was completed. String

Payment statuses (inferred_payment_status, bank_payment_status, pg_payment_status, aggregator_payment_status) can be one of: SUCCESS, FAILURE or UNKNOWN.

* The attribute url shall be passed only for endUrlReached method

Create BrowserParams Object

BrowserParams class provides an easy-to-use interface to add all the parameters that must be sent to JusPay Safe browser. Create an instance of the class to get started:

BrowserParams browserParams = new BrowserParams();

Find below the set of parameters which must be sent:

Variable Description Type Required Default
url Start URL for payment String Yes
postData POST parameters that must be passed to the URL String No
merchantId Identifies the merchant. Eg. 'merchant’ String Yes
clientId ClientID defines the platform used. Eg. 'merchant_android’ String Yes
transactionId Represents the current transactionId String Yes
orderId Represents the order number assigned by the merchant String Yes
amount Amount of the transaction String Yes
customerId Unique identifier of the customer String No
customerEmail Email address of the customer String No
customerPhoneNumber Mobile number of the customer String No
Short note about transaction shown to the customer. ex. 'Paying INR 200 for Order 123456' String No
remarks Remarks about transaction. This will be automatically filled up in the netbanking page. ex. 'Pay to merchant' String No
clearCookies If true, we will clear webView cookies whenever Juspay Webview is initialized. Set argument to false if you dont want to clear cookies Boolean No true

See the example below:

BrowserParams browserParams = new BrowserParams();


browserParams.setRemarks("Flight MUM DEL");


All values in postData should be URL encoded before setting browserParams.setPostData(PAYMENT_POST_DATA);. If you do not URL encode the values, then your gateway/aggregator will show error message in the browser.

Deprecation Note:

browserParams.setDisplayNote() is deprecated. Please use OnScreenDisplay class.

Custom Parameters

Custom parameters let you add new dimensions which can be very useful for analytics. Please make sure that the dimensions you choose are dense. It does not make sense to put mobile number or email address as a custom parameter.

Variable Description Required
udf_:var1 Custom Field No
udf_:var2 Custom Field No
udf_:var3 Custom Field No
Map<String,String> customParameters = new HashMap<String, String>();
customParameters.put("udf_category", "FLIGHT");

With the above, if you have categories such as FLIGHT, BUS and TRAIN, then you can measure the success rate for each of these categories and compare them with each other.

Custom HTTP Headers

Sometimes you would want to pass more information as HTTP headers to the first URL. BrowserParams class accepts a Map of as custom headers. All the headers set here will be sent to WebView as HTTP headers.

Map<String, String> customHeaders = new HashMap<String, String>();
customHeaders.put("Accept-Encoding", "gzip, deflate, sdch");
customHeaders.put("Accept-Language", "en-US,en;q=0.8");

Define endUrls

Array of Strings each of which will be interpreted as regular expressions. Every URL loaded (in onPageStarted) by the browser will be matched against each of the array items. If a match is found, then the browser stops further processing and delegates the control back to the app via BrowserCallback.

JuspaySafeBrowser.setEndUrls(new String[]{"https://shop\\.com/paymentResponse.*", 

Hint: Be sure to escape the dots as required. Note the final .* is deliberately not escaped.

Start the Browser

Now, start the browser and wait for it to complete. This starts the payment activity and gives the callback when aborted or successful.

  JuspaySafeBrowser.start(this, browserParams, callBack);