> ## Documentation Index
> Fetch the complete documentation index at: https://ownpay.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> OwnPay is licensed under AGPL-3.0 and is completely free - no licensing fees.
> Production docs URL: https://ownpay.org/docs - append .md to any page URL for clean markdown.
> OwnPay requires PHP 8.3+, MySQL/MariaDB, and Redis.
> MCP server available at https://ownpay.org/docs/mcp for programmatic documentation queries.
> Use root-relative links (e.g. /quickstart) for internal navigation - do NOT include /docs prefix.
> Plugin development: consult /developer/plugins/ pages for correct interfaces and manifests.
> Canonical locations: API auth = /api/authentication, webhook verification = /api/webhooks, rate limits = /resources/rate-limiting, transaction statuses = /fundamentals/payment-flow.
> The documentation uses the Diataxis framework: Tutorials (learning), How-to (tasks), Reference (lookup), Explanation (understanding).

# Companion App

> Install and pair the Android companion app to forward incoming payment confirmation SMS (bKash, Nagad, Rocket, etc.), send heartbeats, and receive push commands from your OwnPay instance.

The OwnPay Companion App is an Android application that bridges your Android phone with your self-hosted OwnPay instance. Its **sole SMS-related purpose** is forwarding **incoming payment confirmation SMS** (for example, mobile money receipts from bKash, Nagad, Rocket, Upay) to OwnPay for automatic transaction verification.

<Warning>
  **The companion app ONLY reads INCOMING SMS messages that contain payment transaction confirmations.**

  * It does **NOT** read, forward, or process outgoing, sent, or draft SMS.
  * It does **NOT** read or process OTP messages, verification codes, or 2FA codes from other services.
  * It does **NOT** read or process personal messages, promotional SMS, or any other non-payment SMS.
  * It applies a privacy filter on-device: only SMS that match known payment receipt patterns are forwarded to your OwnPay server. All other SMS are silently ignored and never leave the device.
</Warning>

<Info>
  The companion app is not available on Google Play. Download the APK directly from the [OwnPay GitHub releases](https://github.com/own-pay/OwnPay) page.
</Info>

## What the app does

* **Receives incoming payment SMS** - Listens for **incoming** SMS and applies a privacy filter that **only** passes through payment confirmation messages (mobile money receipts, bank transfer confirmations)
* **Forwards to OwnPay** - Sends **only** the filtered payment SMS content to your instance via the Mobile API. All non-payment SMS never leave the device
* **Sends heartbeats** - Periodic pings so OwnPay knows the device is online
* **Receives push commands** - Accepts remote instructions from the admin panel

<Note>
  The app has no access to outgoing, sent, or draft messages. It cannot read OTP codes, personal conversations, or any SMS other than incoming payment confirmations.
</Note>

## Install and pair

<Steps>
  <Step>
    Download the latest `ownpay-companion-v0.2.0.apk` from the GitHub releases page and install it on your Android device. You may need to enable **Install from unknown sources** in your device settings.
  </Step>

  <Step>
    Open the app and enter your OwnPay instance URL (for example, `https://pay.yourdomain.com`) and the **Mobile API key** generated from [Devices](/docs/mobile/devices).
  </Step>

  <Step>
    Tap **Pair Device**. The app sends a registration request and displays a confirmation screen with the assigned device name.
  </Step>

  <Step>
    Back in the OwnPay admin panel, go to **Mobile > Devices** and confirm the device appears with an **Online** status.
  </Step>
</Steps>

## Permission requirements

The companion app requires the following Android permissions:

| Permission                                    | Purpose                                                                                                                                                        |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read SMS** (`RECEIVE_SMS`, `READ_SMS`)      | Receive **incoming** payment confirmation SMS only. Outgoing/sent/draft SMS are never accessed. On-device filter blocks all non-payment SMS before forwarding. |
| **Foreground Service** (`FOREGROUND_SERVICE`) | Maintain a persistent connection for heartbeats and push commands                                                                                              |
| **Battery optimization exemption**            | Prevent the OS from killing the background service                                                                                                             |

<Warning>
  Without the battery optimization exemption, Android may aggressively terminate the companion app's background service, causing missed SMS and heartbeat timeouts. Always whitelist the app in your device's battery settings.
</Warning>

## Heartbeat mechanism

The app sends a heartbeat to your OwnPay instance every **60 seconds**. If OwnPay does not receive a heartbeat within **10 minutes**, the device status changes to **Offline** in the admin panel. See [Devices](/docs/mobile/devices) for health monitoring details.

## Troubleshooting pairing

| Symptom                    | Cause                                    | Fix                                                                                       |
| -------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------- |
| `Connection refused` error | Instance URL is incorrect or unreachable | Verify the URL includes `https://` and the server is accessible from the device's network |
| `Invalid API key`          | Wrong or expired mobile API key          | Regenerate the key from the Devices page and re-enter it in the app                       |
| Device shows Offline       | Battery optimization killing the service | Go to Android Settings > Apps > OwnPay > Battery > Unrestricted                           |
| SMS not forwarding         | SMS permission not granted               | Open Android Settings > Apps > OwnPay > Permissions > SMS > Allow                         |

## Related Pages

* [Devices](/docs/mobile/devices) - Manage paired devices and monitor health
* [SMS Templates](/docs/mobile/sms-templates) - Configure regex patterns for SMS verification
* [SMS Center](/docs/notifications/sms-center) - View incoming payment SMS logs and outbound notification queue


## Related topics

- [OwnPay Ecosystem - SDKs, Plugins, Companion App, and Marketplace](/docs/resources/ecosystem.md)
- [List Companion App Notifications](/docs/api-reference/list-companion-app-notifications.md)
- [Pair Mobile Companion Device](/docs/api-reference/pair-mobile-companion-device.md)
- [SMS auto-verification](/docs/gateways/sms-verification.md)
- [Common Errors](/docs/resources/common-errors.md)