> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/payments/android-app-integration.md).

# 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](https://developers.bead.xyz/payments/create-payment.md) and [Quick Start](https://developers.bead.xyz/quick-start.md) 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:

1. Let the hosted page tell the app when to close the WebView.
2. Return to the app when checkout completes or is cancelled.
3. 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.

```kotlin
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
```

**Step 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:

```kotlin
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:

```json
{"paymentUpdate":null,"quoteResponse":null,"selectedCurrency":null,"initResponse":null}
```

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:

```kotlin
webView.webViewClient = object : WebViewClient() {
    override fun shouldOverrideUrlLoading(
        view: WebView,
        request: WebResourceRequest
    ): Boolean {
        val uri = request.url
        if (uri.scheme == "myapp" && uri.host == "payment-return") {
            // Close the WebView, then confirm the outcome with your backend.
            finish()
            return true
        }
        return false
    }
}
```

Use both mechanisms together. They cover different moments:

| Mechanism                    | When it happens                                                      | What your app does                        |
| ---------------------------- | -------------------------------------------------------------------- | ----------------------------------------- |
| `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](https://developers.bead.xyz/payments/payment-webhooks.md).

`completed` and `overpaid` are paid. `underpaid`, `expired`, `invalid`, `cancelled`, and `abandoned` are not paid. See [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses.md).

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)`, open `chrome://inspect`, and run `typeof window.ReactNativeWebView` in the page. It should return `object`.
* 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](https://developers.bead.xyz/payments/payment-statuses.md) for full status definitions
* Configure [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks.md) for server side confirmation
* Return to [Create Payment](https://developers.bead.xyz/payments/create-payment.md) for request fields, including `redirectUrl`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/payments/android-app-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
