Handling In-Process WebView

Home    APMs    Handling In-Process WebView

On this page:

Overview

In-process WebView is no longer supported when connecting users to their online banking portal using a native mobile app. Desktop and mobile web browser users are NOT affected.

This page explains how to handle in-process WebView for mobile app users.

The following alternative payment methods (APMs) are affected:

  • apmgw_eCheckSelect
  • apmgw_eCheckSelect_DOB
  • apmgw_Secure_Bank_Transfer

Please feel free to contact our Integration Team ([email protected]) or your Relationship Manager if you need further assistance.

General Solution

The solution consists of three parts:

  • A new appReturnLink parameter was created to be added to the relevant requests (see Appendix for properties).
  • A new openInExternalBrowser parameter was created to be added to the relevant responses (see Appendix for properties).
  • The native app intercepts any request that contains the “open_in_browser=true” string and opens it in a default external web browser.

Cashier Implementation

Post Messages

This implemenation impacts native mobile app users only.

The changes to the Cashier are summarized as follows:

  • appReturnLink (also known as universal link, deep link, app2app link) added to the HTTPS request.
  • “nativeAppFlow=1” added to the HTTPS request.

Payin Requirements

  1. Add appReturnLink and nativeAppFlow to the HTTPS request to the Cashier page. 
    https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=7296560490361899020&merchant_site_id=239828&user_token=auto&user_token_id=UserID_2609395090&userid=UserID_2609395090&item_open_amount_1=false&item_min_amount_1=1&item_max_amount_1=100&item_name_1=Cashier%20Test%20product&item_amount_1=10&item_quantity_1=1&item_discount_1=0&numberofitems=1&total_tax=0&discount=0&total_amount=10.00&currency=USD&version=4.0.0&encoding=UTF-8&first_name=Alberta&last_name=Bobbethcharleson&address1=123%20test%20st&city=New%20York&zip=12345&country=US&phone1=2135551234&email=3007427314%40gmail.com&payment_method=apmgw_eCheckSelect&success_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&pending_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&error_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fresponse.php&notify_url=https%3A%2F%2Fhome.stefanovweb.eu%2Fdmn.php%3Fdmnorigin%3DCheckSumCalculator&dateOfBirth=1984-01-01&state=NY&appReturnLink=yourapp%3A%2F%2Fnuvei%2Fchase-oauth-return&isNative=1&nativeAppFlow=1&time_stamp=2023-09-29.17%3A30%3A51&checksum=00e117d06fda5df191266ba991fc1da5aac44f5e28d61fc82aac1374d5206dbf&
  2. After these parameters are added, the merchant should start listening for the following JSON string in the post messages:
    ‘{“action”:”open_in_browser”,”url”:”https%3A%2F%2Fexample.com”}’
  3. The Merchant application should open an external browser and load the URL.
  4. At the end of the interaction, the user is redirected to the deep link provided in the appReturnLink parameter.
  5. When the user returns to the application, the following post message should be sent to the Cashier:
    ‘{“action”:”appReturnLinkUsed”}’

If the redirection in Step 4 is not completed automatically, the user is given the option to return to the application manually.

Payout Requirements

  1. Add appReturnLink and nativeAppFlow to the HTTPS request to the Cashier page. 
    https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do?merchant_id=7857978364609937990&merchant_site_id=238748&user_token=auto&merchantLocale=undefined&wd_amount=1.23&wd_currency=USD&country=US&wd_min_amount=1&wd_max_amount=100&user_token_id=Test_4787479511&userid=app2apptest1&time_stamp=2023-09-01%2015:57:48&version=4.0.0&checksum=253d8d37da628671866f06a6e8a4f62e410d62e1d80d299faeb4766b35de2b89&appReturnLink=merchantapp%3A%2F%2Fmerchanttestapp&nativeAppFlow=1
  2. After these parameters are added, the merchant should start listening for the following JSON string in the post messages:
    ‘{“action”:”open_in_browser”,”url”:”https%3A%2F%2Fexample.com”}’
  3. The Merchant application should open an external browser and load the URL.
  4. At the end of the interaction, the user is redirected to the deep link provided in the appReturnLink parameter.
  5. When the user returns to the application, the following post message should be sent to the Cashier:
    ‘{“action”:”appReturnLinkUsed”}’

If the redirection in Step 4 is not completed automatically, the user is given the option to return to the application manually.

This implemenation impacts native mobile app users only.

The changes to the Cashier are summarized as follows:

  • appReturnLink (also known as universal link, deep link, app2app link) added to the HTTPS request.
  • “open_in_browser=true” requests must be intercepted and opened in a default web browser.

Payin Requirements

  1. Add appReturnLink to the HTTPS request to the Cashier page. 
    https://ppp-test.safecharge.com/ppp/purchase.do?currency=EUR&item_name_1=Test%20Product&item_number_1=1&item_quantity_1=1&item_amount_1=50.00&numberofitems=1&encoding=utf-8&merchant_id=640817950595693192&merchant_site_id=148133&time_stamp=2018-05-15.02%3A35%3A21&version=4.0.0&user_token_id=ran100418_scobd%40mailinator.com&user_token=auto&total_amount=50.00&notify_url=https%3A%2F%2Fsandbox.nuvei.com%2Flib%2Fdemo_process_request%2Fresponse.php&theme_id=178113&checksum=3f907ff30d33239880c853ad5bdf0a0aaf3a351de7220d6e2379f8804b58097f&appReturnLink=merchantapp%3A%2F%2Fmerchanttestapp
  2. Update your native app to intercept all requests that contain a string “open_in_browser=true” and open them in a default web browser.
    Example:
    https://ppp-test.safecharge.com/ppp/review.do?open_in_browser=true

After the steps above are completed, an external browser is opened for users for the relevant APMs. At the end of the interaction, the user is redirected to the deep link provided in appReturnLink.

Payout Requirements

  1. Add appReturnLink to the HTTPS request to the Cashier page. 
    https://ppp-test.safecharge.com/ppp/withdrawal/withdraw.do?merchant_id=7857978364609937990&merchant_site_id=238748&user_token=auto&merchantLocale=undefined&wd_amount=1.23&wd_currency=USD&country=US&wd_min_amount=1&wd_max_amount=100&user_token_id=Test_4787479511&userid=app2apptest1&time_stamp=2023-09-01%2015:57:48&version=4.0.0&checksum=253d8d37da628671866f06a6e8a4f62e410d62e1d80d299faeb4766b35de2b89&appReturnLink=merchantapp%3A%2F%2Fmerchanttestapp
  2. Update your native app to intercept all requests that contain a string “open_in_browser=true” and open them in a default web browser.Example:
    https://ppp-test.safecharge.com/ppp/forwarder.html?open_in_browser=true&link=…

After the steps above are completed, an external browser is opened for users for the relevant APMs. At the end of the interaction, the user is informed of the result of the withdrawal request, and is given the option to return to the application.

REST API Implementation

This implemenation impacts native mobile app users only.

  • This flow is relevant only for new users (without UPO).
  • Java SDK is updated to fulfill REST API changes.

The changes to the REST API are summarized as follows:

Payin Requirements

/openOrder Request

A new appReturnLink parameter must be added to the request:

Example /openOrder Request
{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "currency":"USD",
  "amount":"200",
  "userTokenId":"<unique customer identifier in merchant system>",
  "urlDetails":{
    "successUrl":"<URL the customer is directed to after a successful transaction>",
    "pendingUrl":"<URL the customer is directed to when the transaction response is pending>",
    "failureUrl":"<URL the customer is directed to after an unsuccessful transaction>",
    "notificationUrl":"<URL to which DMNs are sent>",
    "appReturnLink":"<deep link to your application>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

/payment Request

A new appReturnLink parameter must be added to the request:

Example /payment Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "currency":"USD",
  "amount":"100",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_APM_Name"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName":"<first name>",
    "lastName":"<last name>",
    "country":"<country>",
    "email":"<user email>"
  },
  "userDetails":{
    "firstName":"<first name>",
    "lastName":"<last name>",
    "country":"<country>",
    "email":"<user email>"
  },
  "urlDetails":{
    "successUrl":"<URL the customer is directed to after a successful transaction>",
    "pendingUrl":"<URL the customer is directed to when the transaction response is pending>",
    "failureUrl":"<URL the customer is directed to after an unsuccessful transaction>",
    "notificationUrl":"<URL to which DMNs are sent>",
    "appReturnLink":"<deep link to your application>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Responses

For /payment and /getMerchantPaymentMethods, Nuvei returns an additional new parameter: openInExternalBrowser (true/false)

Example /payment Response
{
  "orderId":"271308078",
  "userTokenId":"230811147",
  "paymentOption":{
    "userPaymentOptionId":"53959588",
    "card":{
      "ccCardNumber":"4****2535",
      "bin":"400002",
      "last4Digits":"2535",
      "ccExpMonth":"12",
      "ccExpYear":"26",
      "acquirerId":"19",
      "cvv2Reply":"",
      "avsCode":"",
      "cardType":"Credit",
      "cardBrand":"VISA",
      "threeD":{
        
      }
    }
  },
  "openInExternalBrowser":"true",
  "transactionStatus":"APPROVED",
  "gwErrorCode":"0",
  "gwExtendedErrorCode":"0",
  "transactionType":"Sale",
  "transactionId":"1110000000010304183",
  "externalTransactionId":"",
  "authCode":"111361",
  "customData":"",
  "fraudDetails":{
    "finalDecision":"Accept"
  },
  "sessionToken":"cedbd6c0-52cf-4716-83b1-309e8e8dd2d3",
  "clientUniqueId":"12345",
  "internalRequestId":"222320318",
  "status":"SUCCESS",
  "errCode":"0",
  "reason":"",
  "merchantId":"427583496191624621",
  "merchantSiteId":"142033",
  "version":"1.0",
  "clientRequestId":"1C6CT7V1L"
}

If you receive openInExternalBrowser: “true”, and your application operates with WebView, make sure to open the returned navigation link from the relevant method in an external browser.

Payout Requirements

The payout flow is unchanged in the current integration. The only changes required are for /accountCapture. The UPO used in the payout request can be from a deposit or withdrawal.

/accountCapture Request

A new appReturnLink parameter must be added to the urlDetails class in the request:

Example /accountCapture Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "paymentMethod":"apmgw_APM_Name",
  "userTokenId":"<unique customer identifier in merchant system>",
  "currencyCode":"USD",
  "countryCode":"US",
  "amount":"200",
  "languageCode":"en",
  "userDetails":{
    "firstName":"John",
    "lastName":"Smith",
    "address":"22 Main Street",
    "phone":"6175551414",
    "zip":"02460",
    "city":"Boston",
    "state":"MA",
    "email":"[email protected]",
    "country":"US",
    "birthdate":"2000-06-30"
  },
  "urlDetails":{
    "successUrl":"<URL the customer is directed to after a successful transaction>",
    "pendingUrl":"<URL the customer is directed to when the transaction response is pending>",
    "failureUrl":"<URL the customer is directed to after an unsuccessful transaction>",
    "notificationUrl":"<URL to which DMNs are sent>",
    "appReturnLink":"<deep link to your application>"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  }
}

/accountCapture Response

Nuvei returns an additional new parameter: openInExternalBrowser (true/false) in the response.

Example /accountCapture Response
{
  "reason":"",
  "redirectUrl":"https://pay-pd-mint.mazooma.com/bank-select?code=3e2ccaa1-76e5-40eb-b11c-4ef56b2e98b6&merchant-return-url=https%3A%2f%2fjumpbox.safecharge.com%2fdmz%2fApmConnector%2fbankCapture%2f9E8AD967448FB187B6A7F97CE9123ED8",
  "merchantId":"2502136204546424962",
  "openInExternalBrowser":"true",
  "errCode":0,
  "sessionToken":"c02dd5dc-9119-4de1-8192-0b8cdcb02650",
  "userTokenId":"MJIKY53AK9K7",
  "internalRequestId":19287531,
  "version":"1.0",
  "status":"SUCCESS",
  "merchantSiteId":"126006"
}

If you receive openInExternalBrowser: “true”, and your application operates with WebView, make sure to open the returned navigation link from the relevant method in an external browser.

Web SDK Implementation

The changes to the Web SDK are summarized as follows:

  • /openOrder: appReturnLink added to request
  • createPayment() and accountCapture(): These methods might trigger a redirection to a link that contains “open_in_browser=true”, which your native app must intercept and open in an external browser.
  • The getApms() method is informational only.

You must send the appReturnLink parameter in an /openOrder request, as described in REST API Payins.

If openInExternalBrowser: “true” is returned in the createPayment() and accountCapture() methods, your native app must intercept any request that contains “open_in_browser=true” and open it in an external browser.

Example createPayment() Response
{
  "result":"DECLINED",
  "errCode":-1,
  "errorDescription":"Decline",
  "openInExternalBrowser":true,
  "userPaymentOptionId":14958143,
  "ccCardNumber":5****5761,
  "bin":511142,
  "last4Digits":5761,
  "ccExpMonth":09,
  "ccExpYear":21,
  "transactionId":1110000000004146935,
  "threeDReason":,
  "threeDReasonId":,
  "challengeCancelReasonId":,
  "challengeCancelReason":,
  "isLiabilityOnIssuer":1,
  "challengePreferenceReason":12,
  "cancelled":false
}
Example accountCapture() Response
{
  "errCode":0,
  "internalRequestId":32340521,
  "merchantId":8256777005602846935,
  "merchantSiteId":112106,
  "openInExternalBrowser":true,
  "reason":,
  "redirectUrl":"https":,
  "sessionToken":fd355afa-7af5-4e14-a757-02bd7c3d5ce7,
  "status":"SUCCESS",
  "userTokenId":bankCaptureUser4,
  "version":1.0
}

Simply Connect Implementation

The changes to the Simply Connect are summarized as follows:

  • /openOrder: appReturnLink added to request
  • The native app must intercept any link containing open_in_browser=true” and open it in an external browser.

You must send the appReturnLink parameter in an /openOrder request, as described in REST API Payins.

Testing the App

For payment methods that leverage Plaid to authenticate users with their bank (such as Secure Bank Transfer or Mazooma), you can select one of the following App2App banks to test:

  • Chase
  • First Platypus Bank

The flow below is a sample user experience once the changes described in this page are made.

  1. The user initiates the APM with Plaid flow.

    If you are able to see the website URL in an external browser, then you have completed the necessary changes.


  2. The user selects First Platypus Bank or Chase bank to test. First Platypus Bank is used here.
  3. The user is prompted that they will be redirected to their banking app.
  4. The bank login screen appears.
  5. The user selects a verification method and enters the information.
  6. The user enters the verification code that is sent.
  7. The user selects the account.
  8. The user confirms the selection.
  9. The user confirms the information.
  10. A confirmation screen opens.
  11. After a few moments, you should be redirected back to the native app.
    If for some reason, the redirect does not work, the screen below opens. The user presses the button to return to the native app.

Appendix

New field: appReturnLink

Description: The deep link used to return to the merchant’s native application.

Max length: 512

Field type: String

URL encoding: The app link must be URL encoded.

Example: app://your.app.link must be encoded to app%3A%2F%2Fyour.app.link

New field: openInExternalBrowser

Description: Indicates if an external browser needs to be opened by the native app.

Possible values: true/false

Field type: String

Example: “openInExternalBrowser”: “true”

Last update iconLast modified September 2024