In-app browsers with Embed

Some of the most popular apps on mobile (and some on desktop) rely on in-app browsers to keep a user within the app while browsing third-party sites. Notable examples of these include Facebook, Instagram, and other Meta apps on mobile.

Although these in-app browsers mostly look like regular web browsers they have some irregular behavior when it comes to dealing with opening new tabs and windows, a feature that Embed relies on when dealing with alternative and local payment methods.

As a result of this irregular behavior the browser might not redirect to these payment services, or if a redirect does happen the original merchant checkout page may be lost. The consequence of this is that in some edge cases the transaction may complete successfully but your site would not be directly notified of this in the customer’s browser. Additionally, the customer may be left with a browser window that does not close to reveal your checkout page.

​

Integration

In addition to our general best practice guidance, we recommend you add support for a return URL to handle in-app browsers, detailed below.

​

Set a return URL to handle in-app browsers

To prevent the possibility for some customers using in-app browsers to be left without a direct link back to your site, we recommend setting the optional fullPageReturnUrl. When the fullPageReturnUrl is set as well as redirectMode=fallback then Embed will first attempt its normal redirect behavior and only if Embed detects a situation where the normal redirect cannot occur (for example when your customer is accessing your application from one of these in-app browsers) it will redirect the customer to your fullPageReturnUrl, appending it with the transaction ID and transaction status.

[fullPageReturnUrl]?transaction_id=2f37e0d0-5549-42c4-9c5c-e03d5fa97148&transaction_status=capture_succeeded

Your application should host a page at the fullPageReturnUrl that handles the resulting customer redirection for those edge cases.

If preferable, you can set the redirectMode to fullPage to always redirect to the fullPageReturnUrl. This can be very useful when testing your return URL integration.

Here is an example of how these properties can be set when configuring Embed.

embed.setup({
  fullPageReturnUrl: "https://example.com/checkout/callback"
  // Setting the redirectMode to fullPage forces the uses of this return URL
  redirectMode: "fullPage" 
  // The redirectMode defaults to "fallback" which will try to use a popup first before
  // falling back to a full page redirect.
})