In-depth Knowledge

Mobile Integration / Native App

In this section, we walk through how to present the Brite Client inside a native iOS or Android app, so your customers can approve payments in their banking app and come straight back to yours.

In most markets, banks hand the customer over to their banking app through HTTPS links. An in-app browser hands these links to the banking app reliably. In a WebView, the result varies by device and bank, and the banking app often doesn’t open. Follow these steps to set up your app:

How the app flow works
Create the session for an app
Register your app’s URL scheme
Open the Brite Client on iOS
Open the Brite Client on Android
Handle the return to your app
If you use a WebView
Mobile web
Testing your app integration
Implementation Tips

1. How the app flow works

Open the Brite Client in an in-app browser: SFSafariViewController on iOS, or Auth Tab / Chrome Custom Tabs. These components behave like the device’s browser, so the operating system can hand the customer over to their banking app.

A typical deposit in an app runs as follows:

Your backend creates the session with session.create_deposit and sends your app’s URL scheme in deeplink_redirect.
Your app opens the session url in the in-app browser.
The customer selects their bank. The bank’s HTTPS link opens the banking app, where the customer approves the payment.
The bank returns the customer to the mobile browser, and Brite redirects to your app’s URL scheme. The customer is back in your app, where the Brite Client is still open and finishes the session.
When the session reaches its final state, Brite redirects to your URL scheme again. Your app closes the in-app browser and asks your backend for the result, which confirms it with session.get or transaction.get.

Why not a WebView? A WebView can load the bank’s HTTPS link itself instead of handing it to the banking app. The customer may then see the bank’s web login, or get no response at all, and the session can be lost while they are away. See If you use a WebView.

2. Create the session for an app

When the session is started in your app, send your app’s custom URL scheme in deeplink_redirect. Brite uses it to bring the customer back to your app. In a typical payment this happens twice:

When the customer returns from their banking app after approving the payment
When the session reaches its final state: completed, failed or aborted

Depending on the bank and the device, the customer may not leave the in-app browser, so your app can receive only the final redirect. Whichever redirect arrives, keep the Brite Client open until the session reaches its final state, and check the state with your backend each time your URL scheme is opened. You don’t need to send redirect_uri for app sessions.

Example request

				
					{
  "country_id": "gb",
  "amount": 25.00,
  "merchant_reference": "<unique reference>",
  "deeplink_redirect": "com.example.myapp://brite-return",
  "callbacks": [
    { "session_state": 10, "url": "https://api.example.com/brite/callback" },
    { "session_state": 11, "url": "https://api.example.com/brite/callback" },
    { "transaction_state": 2, "url": "https://api.example.com/brite/callback" },
    { "transaction_state": 3, "url": "https://api.example.com/brite/callback" },
    { "transaction_state": 5, "url": "https://api.example.com/brite/callback" },
    { "transaction_state": 7, "url": "https://api.example.com/brite/callback" }
  ]
}

Note

Use a scheme unique to your app, such as your bundle or package name (com.example.myapp://). Universal Links and App Links are not supported as a return URL at the moment.

For the full list of parameters, see session.create_deposit.

3. Register your app's URL scheme

Register the custom URL scheme you send in deeplink_redirect, so the operating system opens your app when Brite redirects to it. Follow Apple’s and Google’s guidelines for each platform:

Choose a unique scheme. Use your bundle or package name, for examplecom.example.myapp, so it doesn’t clash with other apps.
Register it on iOS. Add the scheme under URL Types in your app’s Info settings. See Apple’s guide Defining a custom URL scheme for your app.
Register it on Android. Add an intent filter for your scheme to the activity that handles the return, with the VIEW action and the DEFAULT and BROWSABLE categories. See Android’s guide Create deep links to app content.
Handle the incoming URL in the screen that started the payment, as described in step 6.

Important Note

If several apps register the same scheme, the operating system can open any of them. Use a unique scheme, never put sensitive data in the return URL, and treat it only as a sign that the customer is back.
The browser may ask the customer to confirm opening your app when Brite redirects to your scheme. This is expected.
On Android, declare the return activity as exported and reuse your existing payment screen, so the return doesn’t open a second copy of it.

4. Open the Brite Client on iOS

Open the session url returned by session.create_deposit in an SFSafariViewController. It handles HTTPS links like Safari, so the bank’s link opens the banking app when it is installed. See Apple’s SFSafariViewController documentation for how to present it.

Present the session URL in SFSafariViewController, full screen or as a large sheet.
Keep it open when the customer returns from their banking app. The first redirect to your URL scheme brings the customer back to your app, and the Brite Client continues in SFSafariViewController.
Dismiss it when the session reaches its final state. Check the session state with your backend each time your URL scheme is opened, and dismiss SFSafariViewController only once the session is in a final state, as described in step 6.
Handle the Done button. If the customer closes SFSafariViewController, check the result too. They may have approved the payment before closing it.

Important Note

After the customer approves in their banking app, the bank returns them to Safari, not to your app. Brite then redirects Safari to your URL scheme, and iOS asks the customer to open your app. Don’t dismiss SFSafariViewController at this point: the Brite Client in it still has to finish the session.
Don’t use a WKWebView for the Brite Client. See If you use a WebView.
Don’t place overlays, loaders or extra buttons on top of the Brite Client.

5. Open the Brite Client on Android

Open the session url in an Auth Tab or a Chrome Custom Tab. Both handle HTTPS links like the browser, so the bank’s link opens the banking app when it is installed. See Chrome’s guides Simplify authentication using Auth Tab and Custom Tabs.

Add the AndroidX Browser library to your app. It provides both Auth Tab and Custom Tabs.
Open the session URL in the tab of your choice.
Keep the tab open when the customer returns from their banking app. That redirect usually comes from the device’s browser, so it arrives through your intent filter while the tab stays open to finish the session.
Close the tab only when the session reaches its final state. Each time your URL scheme is opened, check the session state with your backend.
Check the result as described in step 6 when the session ends or the customer closes the tab.

6. Handle the return to your app

The redirect to your app tells you the customer is back, not whether the payment succeeded. Always confirm the result on your backend before you show it or credit the customer.

Wait for the final redirect. Both redirects use your URL scheme. When one arrives, ask your backend for the session state, and close the Brite Client only when the session is in a final state (10, 11 or 12) or the customer closes the in-app browser.
Ask your backend for the result. Your backend calls session.get with the session id and reads its state, and transaction.get for the transaction.
Show the outcome. A completed session means the customer approved the payment. Show a processing message until your backend has confirmed it.
Credit on the callback. Credit the customer’s balance when you receive the transaction state 5 (STATE_CREDIT) callback, and confirm the details with transaction.get before you update your system. See Callback handling.

Important Note

The customer can come back to your app in more than one way: through the redirect, by closing the in-app browser, or by switching apps manually after approving in their bank. Check the result from your backend whenever your payment screen becomes active again, not only when the redirect arrives.

For the meaning of each state, see Session States and Transaction States.

7. If you use a WebView

We don’t recommend a WebView, because you can’t predict what happens when the customer selects their bank. The same bank can behave differently depending on the device, the operating system version and how the WebView is configured. Sometimes the banking app opens as expected, but often one of these happens instead:

Nothing happens. The WebView swallows the link, and the customer is left on the Brite Client with no response.
The bank’s web login opens inside the WebView. The customer has to log in with a password or card reader instead of biometrics, and some banks restrict login in embedded browsers.
The payment session is lost. While the customer is in their banking app, the operating system is more likely to close or reload a WebView than an in-app browser to free memory. When that happens, the customer comes back to a blank or restarted screen and the session can’t continue.

If you can’t avoid a WebView, set it up so the customer can still finish the payment when the banking app doesn’t open:

Offer bank links to the operating system first. When the WebView navigates to an HTTPS link outside the Brite Client and your own pages, ask the operating system to open it only if an app is registered for it, and load it in the WebView if none is. Follow Apple’s and Google’s guidance for opening links in apps.
Let the bank’s web login work. Allow the bank’s pages to load in full, including JavaScript, cookies and redirects, so the customer can approve on the bank’s website when no app opens.
Keep the WebView alive. Don’t destroy or reload it when your app goes to the background, so the session is still there when the customer returns from their banking app.
Check the result when your payment screen is shown again, as described in step 6, in case the WebView was reloaded or closed.
Pass non-HTTP links to the operating system. Identification apps might use custom schemes. Open any URL that isn’t http or https with the operating system instead of loading it in the WebView.

Important Note

Even with these settings, the banking app may not open and the session can still be lost. Test with the main banks in each market you launch in, and use an in-app browser for the most reliable experience.

8. Mobile web

If customers pay on your website in a mobile browser, render the Brite Client as described in Rendering the Brite Client. The browser opens the banking app automatically.

For web sessions, send an HTTPS URL to your website as redirect_uri and leave out deeplink_redirect. An app scheme sent from a browser session strands customers who don’t have your app, and pulls those who do out of the browser where they started.

9. Testing your app integration

The Test Bank in sandbox approves payments on a web page and never hands over to a banking app. Sandbox confirms your session setup, return handling and callbacks, but not the switch to the banking app.

Test these cases on real iOS and Android devices before go-live:

The Brite Client opens in SFSafariViewController on iOS or Auth Tab / Custom Tab on Android
Returning from the banking app brings the customer back to your app with the Brite Client still open
The Brite Client closes only when the session reaches its final state, and your app confirms the result with your backend
Closing the in-app browser before paying returns to your payment screen and shows the correct result
A failed or aborted payment shows the right message, and the session state 10 and 11 callback is handled
In production, selecting a bank opens the banking app when it is installed, and the bank’s web login when it isn’t

10. Implementation Tips

In-app browser, not WebView
Use SFSafariViewController on iOS or Auth Tab / Custom Tabs on Android, so banking apps open automatically.
Return with deeplink_redirect
For app sessions, send your app’s custom URL scheme in deeplink_redirect only, and close the Brite Client only after the session’s final state. For web sessions, send an HTTPS redirect_uri and leave out deeplink_redirect.
Never trust the redirect
Confirm every result on your backend, and credit the customer on the transaction state 5 callback.
Clean UI
Your own screens can come before and after the Brite Client, but don’t place loaders, overlays or extra buttons on top of it.
Test on real devices
The sandbox Test Bank doesn’t open a banking app, so test the app switch in production before launch.