Android App Integration
Use this guide when a native Android app loads the Bead hosted payment page in a WebView. Web and digital checkout integrations do not need it. Follow Create Payment and Quick Start instead.
The hosted payment page runs in an Android WebView, but the WebView needs a few settings and one small piece of code. Without them, the customer can end up on a screen with no close button and no way back to your app.
Keep your terminal API key on your server. Create the payment from your backend, then pass only
paymentUrls[0]to the app. Do not embed the API key in the app.
How it fits together
Your app needs to do three things:
Let the hosted page tell the app when to close the WebView.
Return to the app when checkout completes or is cancelled.
Confirm the payment outcome with your backend before fulfilling anything.
Step 1: Configure the WebView
Enable JavaScript and DOM storage. The hosted page keeps its checkout state in the browser's local storage, so DOM storage should be on.
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = trueStep 2: Expose the ReactNativeWebView interface
The hosted page looks for a JavaScript object named window.ReactNativeWebView with a postMessage method. When it finds one, the page treats your app as a native app and uses it to signal your app. When it does not, the page behaves like a plain browser, and on screens where there is nowhere to send the customer, it shows no close button.
The name is fixed. The page looks for exactly ReactNativeWebView, whether or not your app uses React Native.
Add the interface before you load the payment URL:
webView.addJavascriptInterface(object {
@JavascriptInterface
fun postMessage(message: String) {
// Called by the hosted payment page. Close the WebView on the main thread.
runOnUiThread { finish() }
}
}, "ReactNativeWebView")
webView.loadUrl(paymentUrl)How the message works:
The page sends a message when the customer taps the close button on a hosted page screen.
On the overpaid and underpaid screens, the page also sends the message automatically once the customer's reclaim email is accepted. The customer does not need to tap anything.
If the reclaim email fails to send, the page does not send the message, and the customer stays on the page.
The message is always the same, and it carries no payment data:
Treat the message only as a signal to close the WebView. Do not read the payload, and do not use it to decide whether a payment was paid. Confirm the outcome as described in Step 4.
Only load Bead hosted payment page URLs in a WebView that has this interface, and ignore the content of the message.
Step 3: Return to your app with redirectUrl
Set redirectUrl when you create the payment to a deep link that opens your app, for example myapp://payment-return. Bead redirects to it after checkout completes or is cancelled, and includes context in the query string. Intercept it in your WebView and close the WebView:
Use both mechanisms together. They cover different moments:
redirectUrl deep link
Checkout completes or is cancelled
Close the WebView and confirm the outcome
ReactNativeWebView message
The customer taps the close button, or the reclaim email is accepted
Close the WebView and confirm the outcome
When the interface is present, the close button sends the message instead of redirecting to redirectUrl.
Step 4: Confirm the outcome
A redirect or a close message tells you the customer left the page. It does not tell you whether the payment was paid. Always confirm the status with your backend before you fulfill an order.
Option A, polling. Have your backend call GET /Payments/{paymentId}/tracking and let your app ask your backend for the result. Poll about every 2 seconds during an active checkout, and stop once the status leaves created or processing.
Option B, webhooks. Configure a terminal level webhook, or pass webhookUrls when you create the payment, and update your order when the status event arrives. See Payment Webhooks.
completed and overpaid are paid. underpaid, expired, invalid, cancelled, and abandoned are not paid. See Payment Statuses.
Polling is a good default for an app that is waiting on the customer, and webhooks are the better source of truth on your server.
Klarna, PayPal, and Venmo
For these tenders, the hosted page opens the provider's checkout in a new window. An Android WebView does not open new windows unless your app supports it, so enable setSupportMultipleWindows(true) and handle onCreateWindow in a WebChromeClient. Test every tender you enable in your app before you go live.
Troubleshooting
The close button is missing
Confirm the interface is registered under exactly
ReactNativeWebView.Confirm you add it before calling
loadUrl. A page that is already loaded does not see an interface added later, so reload the page.In a debug build, enable
WebView.setWebContentsDebuggingEnabled(true), openchrome://inspect, and runtypeof window.ReactNativeWebViewin the page. It should returnobject.Without the interface, the close button only appears when the payment was created with a
redirectUrl.
The close button appears but nothing happens
Confirm your
postMessage(String)method is annotated with@JavascriptInterface.Confirm the method closes the WebView on the main thread. JavaScript interface methods run on a background thread.
The customer returns to the app but the status is unknown
This is expected. The redirect and the close message do not carry a status. Confirm it with polling or webhooks as described in Step 4.
Next steps
Review Payment Statuses for full status definitions
Configure Payment Webhooks for server side confirmation
Return to Create Payment for request fields, including
redirectUrl