Integration

Telr, for when the money has to land in a UAE bank

Telr is a UAE-licensed payment gateway that settles AED into a local bank account, which is why GCC bots use it over international processors. It works as a Telegram Payments provider and as a hosted checkout. It requires a UAE trade licence and a merchant account before anything can be built.

Telr integration: auth, limits and availability

Auth model: API key
Settlement: Multi-day cycle to a UAE bank account
GCC availability: UAE primary market; requires a mainland or free-zone entity with a trade licence
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

The reason Telr appears in almost every UAE bot project is settlement, not features. A restaurant, clinic or rental business needs the money in an AED account at a bank it already deals with, on a settlement cycle its accountant recognises. International processors can often take the payment and struggle to complete that last step cleanly for a UAE entity, and discovering it after the build is an expensive way to learn.

The second reason is onboarding. Telr underwrites UAE businesses as its core market, so a mainland or free-zone company with a trade licence is a normal applicant rather than an exception requiring explanation. That difference sounds administrative and is often the whole timeline: a build that waits six weeks for a merchant account is a build that missed its season.

What Telr is not is a modern developer-first API in the style of Stripe. The integration surface is older, the documentation assumes a hosted-page model, and the ergonomics reflect a gateway designed around web checkout rather than around a chat. None of that prevents a good implementation; it does mean the integration takes longer than the equivalent Stripe work and should be scoped that way rather than discovered mid-project.

How the data actually moves

The order is written before payment is requested and confirmed only from the server-side callback. The customer never returns from Telr carrying anything the Worker treats as authoritative.

Telr authenticates with a store id and an authentication key held server-side. Neither ever reaches the client or the Mini App bundle. Requests are made from the Worker, and the response is verified against the transaction reference we generated rather than trusted from whatever the browser was redirected back with — a redirect parameter is a claim, not a confirmation.

Auth model: API key

Their limits, and what they mean for you

Telr settlement to a UAE bank account typically runs on a multi-day cycle, with the exact terms set in your merchant agreement.

Cash-flow planning is a contract question rather than an engineering one. It matters most for rental and deposit flows, where the money is held and returned rather than simply collected.

Authorisation holds and their maximum duration depend on your merchant category and acquirer, not on Telr's API.

Whether you can place a hold for a car rental deposit rather than a full charge is confirmed with your account manager during scoping. A build that assumed holds and got charges is a different refund burden entirely.

Telr supports AED alongside a set of other currencies, but multi-currency pricing depends on what your merchant account is enabled for.

A bot quoting USD to an international audience while settling AED needs that enabled explicitly. It is not a code change and it is not instant.

Test and live environments use separate store credentials.

The switch to live is a configuration change with a real failure mode: a bot pointed at test credentials takes orders that never charge anyone. The deployment checks which environment it is in and refuses to start in test mode under a production build.

How it fails, and what happens when it does

A customer abandons the hosted payment page and never returns to Telegram.

The order sits in a pending state. Pending orders expire on a timer and release any held stock or slot, because an abandoned checkout that holds inventory indefinitely is indistinguishable from a sale nobody can make.

The callback arrives twice, or arrives after the customer has already been shown a result.

Order confirmation is idempotent on the transaction reference. Duplicate callbacks are common across gateways and produce double fulfilment in any implementation that assumes one.

The gateway is reachable but returns a decline with a generic reason.

The customer is told the payment did not go through and offered an alternative — usually cash on delivery, which most GCC operators support anyway. Relaying a raw gateway error code to a customer is not communication.

The callback never arrives at all because of a transient network fault.

A reconciliation job queries Telr for the status of any order still pending past a threshold, rather than waiting for a message that is not coming. Gateways are not queues and should not be treated as one.

Availability in the UAE and the wider GCC

United Arab Emirates

Telr's primary market. A mainland or free-zone entity with a valid trade licence is a standard applicant, and AED settles to a local bank account.

Saudi Arabia

Available, with its own onboarding requirements and settlement arrangements. Confirm both against your Saudi entity rather than assuming the UAE terms carry across.

Wider GCC and beyond

Coverage varies by country and by merchant category. This is the first thing to confirm with Telr directly, because it determines whether the integration is viable at all before anyone writes code.

Crypto and virtual assets

Conventional card gateways generally will not underwrite virtual asset businesses. A VARA-regulated project needs a different rail entirely, and TON or USDT is usually the honest answer.

When not to use this integration

You have no UAE entity or trade licence. Telr underwrites businesses, not individuals, and there is no version of this that starts before the merchant account does.
You are selling virtual assets or crypto services. Card gateways do not underwrite this category, and a build planned around one will stall at underwriting.
You are selling purely digital goods to a Telegram audience at low price points. Telegram Stars will convert better and needs no merchant account at all.
You need settlement outside the GCC. Telr's advantage is local settlement; without that requirement, the comparison against an international processor is much less one-sided.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Server-side gateway calls, so credentials never reach a client.
Cloudflare D1	current	Order records written before payment and confirmed from the callback.
Zod	4.4	Validation of callback payloads, which arrive from outside your control.
grammY	1.45	Invoice presentation and the return-to-chat flow.

Questions that come up during scoping

Why choose Telr over Stripe for a UAE business?

Settlement and onboarding. Telr settles AED to a local bank account and underwrites UAE entities as its core market. If neither of those matters to you, the argument for Telr weakens considerably and Stripe's developer experience is better.

What do we need before development can start?

A trade licence, an approved merchant account, and test store credentials. The merchant account is the long pole and is almost always the thing that sets the project timeline, so it is worth starting before the build is commissioned.

Does Telr support authorisation holds for rental deposits?

That is set by your merchant category and acquirer rather than by the API, so it is confirmed with your Telr account manager during scoping. A rental flow designed around holds and delivered with charges is a different product and a much larger refund burden.

What happens if the payment callback never arrives?

A reconciliation job queries Telr for the status of any order still pending past a threshold. Waiting for a callback that a transient fault swallowed is how orders end up permanently pending, and gateways are not queues.

Do the customer's card details ever touch our systems?

No. Payment happens on Telr's hosted page, so card data never reaches the Worker or the bot. That keeps your PCI scope minimal, which is the correct arrangement for a business of this size.

How do we avoid accidentally launching against test credentials?

The deployment refuses to start in test mode under a production build. It sounds paranoid until it happens — a bot cheerfully taking orders that charge nobody looks completely healthy from the outside for as long as it takes to notice.