Start the browser

Pre-requisites

Before being able to start the browser, you have to create the following

  1. Setup a mechanism to tell when the payment ends
  2. Create the parameters bundle to initialize the browser correctly

The below sections explain how to achieve these steps. We also provide you with a way to customize the look of the ActionBar.

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

Method ontransactionAborted is invoked when the user clicks back button in the payment flow. We assume the intent of the user is to cancel the transaction.

If you want detailed information of session you can use the parameterized abstract method ontransactionAborted(JSONObject sessionInfo).

endUrlReached

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 as an argument to this function.

A detailed information about the session can be found in the parameterized method endUrlReached(JSONObject sessionInfo).

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() {

  @Override
  public void ontransactionAborted() {
    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.
    PaymentActivity.this.retryPayment();
  }

  @Override
  public void endUrlReached(String url) {
    // 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.
    PaymentActivity.this.startNextActivity();

  }
};

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

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
displayNote
(Deprecated)
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.setMerchantId("shop");
browserParams.setClientId("shop_android");
browserParams.setOrderId("ord_111222");
browserParams.setTransactionId("txn_111222");
browserParams.setAmount("12019.50");

browserParams.setCustomerId("9988776655");
browserParams.setCustomerEmail("user@mail.com");
browserParams.setCustomerPhoneNumber("9988776655");

browserParams.setRemarks("Flight MUM DEL");

browserParams.setUrl(PAYMENT_URL);
browserParams.setPostData(PAYMENT_POST_DATA);

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");
customParameters.put("udf_city","BANGALORE");
customParameters.put("udf_cardbrand","VISA");
browserParams.setCustomParameters(customParameters);

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");
browserParams.setCustomHeaders(customHeaders);

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.*", 
    "https://beta\\.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);