Telegraft

Интеграция

Telr — когда деньги должны лечь на счёт в банке ОАЭ

Telr — лицензированный в ОАЭ платёжный шлюз, который перечисляет дирхамы на местный банковский счёт, и именно поэтому боты в Заливе берут его вместо международных процессингов. Он работает и как провайдер Telegram Payments, и как размещённая у провайдера страница оплаты. До начала разработки нужны торговая лицензия ОАЭ и торговый аккаунт.

Telr — интеграция: доступ, лимиты и доступность

Модель авторизации
Ключ API
Расчёты
Цикл в несколько дней на банковский счёт в ОАЭ
Доступность в Заливе
ОАЭ — основной рынок; нужна компания с материка или из свободной зоны с торговой лицензией
Поток данных
5 переходов, через воркер

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

Зачем нужна эта интеграция

Telr появляется почти в каждом проекте бота для ОАЭ из-за расчётов, а не из-за функций. Ресторану, клинике или прокату нужно, чтобы деньги оказались на дирхамовом счёте в банке, с которым они и так работают, и в том расчётном цикле, который узнаёт их бухгалтер. Международные процессинги нередко способны принять платёж и с трудом доводят до конца этот последний шаг для компании из ОАЭ, а узнавать об этом после завершения разработки — дорогой способ учиться.

Вторая причина — подключение. Telr берёт в работу бизнес из ОАЭ как свой основной рынок, поэтому компания с материка или из свободной зоны с торговой лицензией здесь обычный заявитель, а не исключение, требующее пояснений. Звучит как административная деталь, а на практике это нередко весь график: разработка, которая шесть недель ждёт торговый аккаунт, — это разработка, промахнувшаяся мимо сезона.

Чего у Telr нет — так это современного API в духе Stripe, сделанного под разработчика. Интеграционная поверхность старше, документация исходит из модели с размещённой страницей оплаты, а эргономика отражает шлюз, спроектированный вокруг веб-оплаты, а не вокруг переписки. Хорошей реализации это не мешает; но работы выходит больше, чем в эквивалентной задаче на Stripe, и закладывать это надо в оценку, а не обнаруживать посреди проекта.

Как на самом деле движутся данные

Покупательв TelegramзаказВоркер ботасоздание платежаШлюз Telrобратный вызовВоркер ботаподтверждениеЗаписьзаказа в D1
Заказ записывается до запроса оплаты и подтверждается только серверным обратным вызовом. Покупатель никогда не возвращается от Telr с чем-то, что воркер считал бы достоверным.

Telr авторизует запросы идентификатором магазина и ключом аутентификации, которые лежат на сервере. Ни то ни другое никогда не доезжает до клиента или до бандла Mini App. Запросы уходят из воркера, а ответ сверяется со сгенерированной нами ссылкой на транзакцию, а не принимается на веру из того, с чем браузер вернулся по редиректу: параметр редиректа — это утверждение, а не подтверждение.

Модель доступа: API-ключ

Их лимиты и что они означают для вас

Перечисление средств Telr на банковский счёт в ОАЭ обычно идёт циклом в несколько дней, а точные условия зафиксированы в вашем торговом договоре.

Планирование денежного потока здесь вопрос договора, а не инженерии. Сильнее всего это бьёт по аренде и депозитам, где деньги удерживают и возвращают, а не просто собирают.

Возможность холда авторизации и его максимальный срок зависят от вашей торговой категории и эквайера, а не от API Telr.

Сможете ли вы поставить холд под депозит за аренду авто вместо полного списания — подтверждается у вашего менеджера на этапе проработки. Разработка, рассчитанная на холды и получившая списания, — совсем другая нагрузка по возвратам.

Telr поддерживает дирхам и ряд других валют, но мультивалютное ценообразование зависит от того, что подключено вашему торговому аккаунту.

Боту, который называет цену в долларах международной аудитории, а рассчитывается в дирхамах, это нужно включить отдельно. Это не правка в коде, и это не делается мгновенно.

Тестовая и боевая среды используют раздельные учётные данные магазина.

Переключение на боевой режим — изменение конфигурации с вполне реальным сценарием отказа: бот, смотрящий на тестовые данные, принимает заказы, которые никому ничего не списывают. Развёртывание проверяет, в какой оно среде, и отказывается стартовать в тестовом режиме под боевой сборкой.

Как это ломается и что происходит потом

Покупатель бросает страницу оплаты и в Telegram уже не возвращается.

Заказ остаётся в состоянии ожидания. Такие заказы истекают по таймеру и освобождают удерживаемый товар или слот: брошенная оплата, бессрочно держащая остаток, неотличима от продажи, которую никто не может совершить.

Обратный вызов приходит дважды или приходит уже после того, как покупателю показали результат.

Подтверждение заказа идемпотентно по ссылке на транзакцию. Дублирующиеся вызовы встречаются у всех шлюзов и дают двойное исполнение заказа в любой реализации, которая рассчитывает на один.

Шлюз доступен, но возвращает отказ с общей формулировкой причины.

Покупателю сообщают, что оплата не прошла, и предлагают альтернативу — обычно оплату при получении, которую большинство операторов Залива и так поддерживает. Пересказ покупателю сырого кода ошибки шлюза коммуникацией не является.

Обратный вызов не приходит вовсе из-за кратковременного сетевого сбоя.

Задача сверки запрашивает у Telr статус любого заказа, висящего в ожидании дольше порога, вместо того чтобы ждать сообщение, которое уже не придёт. Шлюз — не очередь, и обращаться с ним как с очередью не стоит.

Доступность в ОАЭ и остальных странах Залива

Объединённые Арабские Эмираты

Основной рынок Telr. Компания с материка или из свободной зоны с действующей торговой лицензией — обычный заявитель, а дирхамы приходят на местный банковский счёт.

Саудовская Аравия

Доступно, со своими требованиями к подключению и своими условиями расчётов. Подтверждайте и то и другое для вашего саудовского юрлица, а не переносите на него условия ОАЭ.

Остальной Залив и шире

Покрытие различается по странам и по торговым категориям. Это первое, что надо уточнить напрямую у Telr, потому что от этого зависит, осуществима ли интеграция вообще, ещё до первой строки кода.

Криптовалюты и виртуальные активы

Обычные карточные шлюзы, как правило, не берут в работу бизнес на виртуальных активах. Проекту под регулированием VARA нужна принципиально другая схема, и честный ответ обычно — TON или USDT.

Когда эту интеграцию делать не нужно

  • У вас нет юрлица в ОАЭ и торговой лицензии. Telr берёт в работу компании, а не физических лиц, и никакого варианта начать раньше торгового аккаунта не существует.
  • Вы продаёте виртуальные активы или криптоуслуги. Карточные шлюзы не берут эту категорию, и разработка, спланированная вокруг одного из них, застрянет на андеррайтинге.
  • Вы продаёте чисто цифровые товары аудитории Telegram с низким чеком. Telegram Stars сконвертируют лучше и торгового аккаунта не потребуют вовсе.
  • Вам нужны расчёты за пределами Залива. Преимущество Telr — местные расчёты; без этого требования сравнение с международным процессингом становится далеко не таким односторонним.

На чём это работает

КомпонентВерсияЗачем
Cloudflare WorkerscurrentСерверные вызовы шлюза, чтобы учётные данные не доезжали до клиента.
Cloudflare D1currentЗаписи заказов, созданные до оплаты и подтверждаемые обратным вызовом.
Zod4.4Валидация тел обратных вызовов, которые приходят извне вашего контура.
grammY1.45Показ счёта и сценарий возврата в переписку.

Вопросы, которые возникают при оценке

Зачем бизнесу из ОАЭ выбирать Telr вместо Stripe?

Из-за расчётов и подключения. Telr переводит дирхамы на местный банковский счёт и берёт в работу компании ОАЭ как свой основной рынок. Если вам не важно ни то ни другое, аргументы за Telr заметно слабеют, а опыт разработчика у Stripe лучше.

Что нужно иметь до старта разработки?

Торговую лицензию, одобренный торговый аккаунт и тестовые учётные данные магазина. Торговый аккаунт — самое длинное звено и почти всегда именно он задаёт сроки проекта, поэтому начинать его стоит до того, как заказана разработка.

Поддерживает ли Telr холды авторизации под депозиты за аренду?

Это определяется вашей торговой категорией и эквайером, а не API, поэтому подтверждается у менеджера Telr на этапе проработки. Сценарий аренды, спроектированный вокруг холдов и сданный со списаниями, — другой продукт и совсем другая нагрузка по возвратам.

Что будет, если обратный вызов об оплате так и не придёт?

Задача сверки запросит у Telr статус любого заказа, который висит в ожидании дольше порога. Ждать обратный вызов, проглоченный кратковременным сбоем, — верный способ навсегда оставить заказы в ожидании, а шлюз очередью не является.

Попадают ли карточные данные покупателя в наши системы?

Нет. Оплата проходит на размещённой у Telr странице, поэтому данные карты не доходят ни до воркера, ни до бота. Это удерживает вашу зону ответственности по PCI минимальной, и для бизнеса такого размера это правильная схема.

Как не запуститься случайно на тестовых учётных данных?

Развёртывание отказывается стартовать в тестовом режиме под боевой сборкой. Звучит как паранойя ровно до первого случая: бот, бодро принимающий заказы, которые никому ничего не списывают, снаружи выглядит абсолютно здоровым — столько, сколько нужно, чтобы это заметить.

Что почитать дальше