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(WebView view, 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 onPageStarted(WebView view, String url) {
    super.onPageStarted(view, url);

  public void onTransactionAborted(JSONObject paymentDetails) {
    GodelTracker.getInstance().trackPaymentStatus(transactionId, GodelTracker.FAILURE);

    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 onWebViewReady(WebView webView) {
    Log.d(TAG, "onWebViewReady: url " + webView.getUrl());

  public void endUrlReached(WebView view, JSONObject sessionInfo) {
    GodelTracker.getInstance().trackPaymentStatus(transactionId, GodelTracker.SUCCESS);

    // 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 A JSON Object that has the user dropout reason JSON
"dropoutReason":["User Aborted"],
realtime A JSON Object that has the system metrics JSON
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.

  • OTP Approved (in realtime) can be one of: NA, auto or manual.

* 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. Boolean No False

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);

User Logout

User should be logged out of Juspay session whenever he logs out of the Merchant App. This ends the user session with Juspay Safe.