---
title: "Telr"
space: "BWH Payments (Next)"
url: "https://docs.bwh.tech/bwh-payments-next/gateways/telr"
updated: "2026-10-10"
---

Take cards and local payment methods across the GCC through [Telr](https://telr.com)'s hosted payment page. Three-decimal currencies such as KWD, BHD and OMR are supported.

Telr doesn't sign its webhooks, so BWH Payments **never trusts them**. It gets every payment's status by asking Telr's authenticated API.

## Before you start

- A Telr store. Test mode is fine.
- Your **Store ID** and **Authentication Key**. For refunds you also need the **Remote API Authentication Key**. All three are in the Telr merchant admin.

## Set up Telr

**1. Fill in Telr Gateway Settings**

| Field | Value |
|---|---|
| Store ID | Your Telr store id |
| Auth Key | The hosted payment page's authentication key |
| Remote Auth Key | Only needed for refunds |
| Currency | Used when a payment has no currency |
| Test Mode | On by default, so orders and refunds are sent as test transactions. Untick it to go live. |
| Authorised URL | Your [confirmation page](/bwh-payments-next/get-started/return-pages). `?reference_id=…` is added to it. |
| Declined URL, Cancelled URL | Your [payment-failed page](/bwh-payments-next/get-started/return-pages) |

**2. Create a Payment Gateway Profile** named `Telr`, set **Gateway Settings** to `Telr Gateway Settings`, and tick **Enabled**.

There's no webhook to set up.

:::note[How payments settle without a webhook]
Your app has to check the status. Call `sync_status()` on the Gateway Payment Request when the shopper returns. Also run a scheduled job that syncs requests that are still Pending, for shoppers who never come back.
:::

## Options

| Option | Default | Turn it on when |
|---|---|---|
| **Treat Authorised As Paid** | Off | Your store authorises and captures in one step (Telr's `ecom` class). On an authorise-only store, leave it off: the money hasn't been collected yet. |

## How it behaves

| Telr status | Payment status |
|---|---|
| Paid | Paid |
| Authorised | Paid with **Treat Authorised As Paid**, otherwise Pending |
| Declined | Not Paid |
| Cancelled | Cancelled |
| Expired | Expired |
| Pending, anything else | Pending |

- **Amounts** are sent as decimals, rounded to the currency's precision. For example, `12.345` KWD.
- **Refunds** go against the settled transaction, and need the Remote Auth Key. Partial refunds are supported.
- **Cancelling** an open checkout isn't supported by Telr. The payment stays Pending until it settles or expires.

## Good to know

- If Telr creates an order but returns no order ref, the checkout fails. BWH Payments never saves a request it can't look up later.
- Telr answers some errors with HTTP 200 and puts the error in the body. BWH Payments reads the body, so you still get a real error message.

## Next steps

- [Gateway reference](/bwh-payments-next/reference/gateway-contract): how `get_payment_status` is used
- [Build a payment gateway](/bwh-payments-next/build/build-a-payment-gateway): add a gateway that isn't listed