> ## 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).

# SMS Templates

> Create and manage regex-based SMS templates that match incoming payment confirmation SMS from mobile money wallets and banks for automatic payment completion.

SMS templates define how OwnPay matches incoming **payment confirmation SMS** from the [companion app](/docs/mobile/companion-app) to pending transactions. Each template binds a **gateway** to a **regex pattern** that extracts the payment amount and transaction ID from the SMS text.

<Note>
  The companion app's on-device privacy filter ensures only incoming payment receipt SMS (for example, bKash/Nagad/Rocket confirmations) are forwarded. OTP messages, personal SMS, and all other non-payment SMS are never sent to the server, so templates only ever process payment confirmation messages.
</Note>

<Info>
  For the full end-to-end auto-verification flow, see [SMS Verification](/docs/gateways/sms-verification).
</Info>

## Template structure

Each SMS template has these fields:

| Field                  | Description                                                                                                           |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Gateway Slug**       | The payment gateway this template applies to (for example, `bkash`, `nagad`, `citybank`)                              |
| **Regex Pattern**      | A PCRE-compatible regular expression that captures the payment amount and/or transaction ID from the confirmation SMS |
| **Code Field Mapping** | Which capture group contains the extracted value (default: group 1)                                                   |
| **Label**              | Human-readable name for the template                                                                                  |
| **Status**             | Active or Disabled                                                                                                    |

## Creating a template

<Steps>
  <Step>
    Navigate to **Mobile > SMS Templates** and click **Add Template**.
  </Step>

  <Step>
    Select the **Gateway** from the dropdown. This ensures the template only matches SMS for transactions on that gateway.
  </Step>

  <Step>
    Enter a **Regex Pattern** that captures the payment details. For example, a bKash payment confirmation SMS might look like:

    ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Tk 500.00 received from 017XXXX1234. TrxID: CN4A7B9D2E. Balance: Tk 1,230.50
    ```

    You would use a pattern like: `Tk ([\d,.]+) received.*TrxID: (\w+)` to capture the amount and transaction ID.
  </Step>

  <Step>
    Set the **Code Field Mapping** to the capture group index that contains the extracted value (usually `1`).
  </Step>

  <Step>
    Click **Save** to activate the template.
  </Step>
</Steps>

## Testing regex patterns

Use the built-in **Regex Tester** at the bottom of the template form. Paste a sample SMS message into the test input, and the tester highlights which capture groups match in real time.

<Tip>
  Always test your regex against multiple real SMS samples before going live. Banks occasionally change their message format, which can break existing templates.
</Tip>

## SMS logs

The lower section of the SMS Templates page displays recent incoming **payment** SMS logs forwarded by the companion app. Use this to:

* **Search** by phone number or transaction ID
* **Filter** by gateway or match status (matched, unmatched, ignored)
* **View raw SMS** by clicking any log row to see the full message text

Unmatched SMS appear with a red indicator. Review these regularly to identify new message formats that need a template update.

## Editing and disabling templates

Click a template's row to edit it. If a gateway changes its SMS format, update the regex pattern and use the tester to confirm it still works. You can **disable** a template without deleting it - this is useful for temporarily pausing verification for a specific gateway.

## Related Pages

* [SMS Verification](/docs/gateways/sms-verification) - Complete auto-verification flow documentation
* [Companion App](/docs/mobile/companion-app) - Android app that forwards incoming payment SMS only
* [SMS Center](/docs/notifications/sms-center) - Centralized SMS monitoring and queue status


## Related topics

- [Update SMS Template](/docs/api-reference/update-sms-template.md)
- [List SMS Templates](/docs/api-reference/list-sms-templates.md)
- [SMS Center](/docs/notifications/sms-center.md)
- [SMS auto-verification](/docs/gateways/sms-verification.md)
- [Common Errors](/docs/resources/common-errors.md)