Android: Redirect Handling

👍

Want the short version? Jump to recommended setup.

Flow modes

When configuring a native alternative payment screen via PONativeAlternativePaymentConfiguration, you choose one of two return redirect modes. For example:

PONativeAlternativePaymentConfiguration(
    flow = Flow.Authorization(
        ...
        configuration = PONativeAlternativePaymentRequestConfiguration(
            returnRedirectType = ReturnRedirectType.MANUAL
        )
    )
)

Manual

In manual mode, the payment app redirects the user directly to the return_url set on the invoice — bypassing ProcessOut’s checkout page entirely. This is the recommended mode when using the SDK, as it results in a simpler redirect chain.

🚧

Some payment methods only support App Links as a return_url. Custom scheme deep links may not be accepted depending on the payment method.

Automatic

In automatic mode, the user is first redirected to the ProcessOut checkout page in a browser, which then redirects to your return_url. The extra hop through ProcessOut’s checkout page provides wider compatibility — in particular, custom scheme deep links work reliably with automatic mode even for payment methods that would otherwise reject them. This is the default behavior.

📘

Use automatic mode if you need custom scheme deep links specifically and cannot use App Links.

Return URL types

Regardless of flow mode, you need to specify an invoice.return_url that brings the user back to your app. There are two options.

App Links

App Links are verified HTTPS URLs associated with your domain that Android routes directly to your app. They are the preferred option: majority of payment methods accept them, and they provide the best and most secure user experience.

Requirements:

• Your domain must be configured for App Links. See Configure Website Associations documentation.

• Set up a web redirect fallback.

Custom scheme deep links

Custom scheme URIs (e.g. yourapp://payment-return) are simpler to set up but come with the following limitations:

• Not accepted by all payment methods. Revolut, for example, requires App Links.

• No landing page required — the custom scheme is intercepted directly.

• Only reliably usable with automatic flow mode.

📘

Use custom scheme deep links only if App Links are not an option for you.

Follow these steps to return to your app by a deep link:

• Set your deep link intent filter following this guide: Handling Android App Links.
• Set your deep link as returnUrl in PONativeAlternativePaymentConfiguration:

PONativeAlternativePaymentConfiguration(
    ...
    redirect = RedirectConfiguration(
        returnUrl = "yourapp://payment-return",
    )
)

User redirect confirmation

When the SDK determines that the user needs to be redirected to a third-party app to authenticate, it prompts the user to confirm before leaving the app. This gives users context about what is happening before they are taken elsewhere.

By default this confirmation is always shown. You can bypass it by setting enableHeadlessMode on the redirect object of your configuration:

PONativeAlternativePaymentConfiguration(
    ...
    redirect = RedirectConfiguration(
        enableHeadlessMode = true
    )
)

When enabled, the SDK will redirect the user automatically (without prompting) — if the redirect requirement is detected during the initial loading of payment information. The bottom sheet will still start automatically when the payment method requires user input in the native UI.

Web redirect fallback

When a direct deep link to the payment app is not possible, the SDK falls back to opening the payment flow in an in-app browser. At the end of the flow, the browser opens your return_url.

🚧

Chrome Custom Tabs do not automatically redirect to your app via App Links; only deep links do.

Follow these steps to return to your app when App Links are required by the payment method:

• Set two intent filters, one for App Link and one for deep link, following this guide: Handling Android App Links.
• Set up a landing page that redirects from your App Link to the deep link.
• Set your deep link as returnUrl in PONativeAlternativePaymentConfiguration:

PONativeAlternativePaymentConfiguration(
    ...
    redirect = RedirectConfiguration(
        returnUrl = "yourapp://payment-return",
    )
)

Landing page

The landing page is an HTML page you host at your App Link URL. The web fallback opens your return_url in the in-app browser. Its job is to redirect the in-app browser to a custom scheme deep link that your app handles — preserving all query parameters from the original URL.

This is your responsibility to build and host. App Link require the landing page to be served from the app’s associated domain.

Minimum requirements:

• Read query parameters from the incoming URL.

• Construct a custom scheme deep link with those parameters preserved exactly.

• Render an explicit button to trigger the redirect — do not rely solely on automatic redirects, as browsers may suppress them.

• Optionally, attempt an automatic redirect as an enhancement, but the explicit button is mandatory.

Recommended setup

The following configuration gives you the best compatibility across payment methods and the smoothest user experience on Android.

1. Use Manual flow mode

Set returnRedirectType to manual on your PONativeAlternativePaymentConfiguration. It produces a simpler redirect chain and is the recommended mode when integrating via the SDK.

PONativeAlternativePaymentConfiguration(
    flow = Flow.Authorization(
        ...
        configuration = PONativeAlternativePaymentRequestConfiguration(
            returnRedirectType = ReturnRedirectType.MANUAL
        )
    )
)

2. Set App Link as invoice.return_url

Ensures compatibility with all payment methods. Must be a URL on a domain associated with your app.

3. Set up a web redirect fallback

Set up a web redirect fallback and a landing page.

4. (Optional) Disable user redirect confirmation

You can enable headless mode to bypass the confirmation screen before redirection. This only applies to payment methods that do not require user input before redirection.