Integration

PayTabs, when you need more than one GCC country

PayTabs is a regional payment gateway with merchant accounts across several GCC countries, which makes it the usual choice for a business operating in more than one. It works behind a Telegram bot as a hosted checkout. Each country is a separate merchant profile with its own settlement.

PayTabs integration: auth, limits and availability

Auth model: API key
Merchant profiles: One per country, each with its own credentials, currency and settlement
GCC availability: Well established in the UAE with AED settlement; strong Saudi coverage
Data flow: 5 hops, worker-mediated

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

Why this integration exists

Businesses that operate in one country pick a gateway on settlement and onboarding. Businesses that operate in three pick on whether one relationship can cover all three, because managing separate gateways per market means separate reconciliation, separate support contacts and separate failure modes for something customers experience as one brand.

PayTabs' position is regional coverage. A group running outlets in the UAE, Saudi Arabia and Egypt can hold profiles under one provider, which simplifies the commercial relationship considerably even though the underlying settlement remains country-specific. That last point matters and gets missed: one provider does not mean one merchant account, one currency or one settlement cycle.

For a bot, the practical consequence is that country is a first-class dimension in the integration rather than a configuration afterthought. Which profile, which currency, which settlement account, and which local payment methods are available are all decided by where the customer is buying — and a bot serving three countries has to route that correctly on every transaction rather than defaulting to whichever profile was set up first.

How the data actually moves

The customer's market is resolved before the payment is created, because it selects the merchant profile, the currency and the settlement account. Confirmation comes from the server callback, never from the browser redirect.

PayTabs authenticates with a profile id and a server key per merchant profile. In a multi-country deployment there is a set of credentials per country, held as separate Worker secrets and selected by the resolved market. Selecting the wrong profile does not fail loudly — it takes a real payment into the wrong account — so the resolution is explicit and logged rather than inferred.

Auth model: API key

Their limits, and what they mean for you

Each country operates as a separate merchant profile with its own credentials, currency and settlement.

A multi-country bot holds several credential sets and must select correctly per transaction. This is the single most consequential detail in a PayTabs integration and the one most often treated as configuration.

Available local payment methods differ by country — mada in Saudi Arabia, for example, is not universally available elsewhere.

The checkout a Saudi customer sees is legitimately different from the one a UAE customer sees. Presenting a uniform payment experience across markets means presenting a worse one in at least one of them.

Settlement currency and cycle are set per profile in your merchant agreement.

Reporting that sums across countries needs an explicit currency policy. A dashboard adding SAR to AED because both are numbers is a class of error that survives a long time before anyone notices.

Test and live credentials are separate per profile.

In a three-country deployment that is six credential sets. The deployment validates that every configured profile is in the same mode, since a partially live configuration is worse than a fully test one.

How it fails, and what happens when it does

The wrong merchant profile is selected for a customer's market.

The payment succeeds into the wrong account and nothing errors. Profile resolution is logged with every transaction so reconciliation catches it in days rather than at a quarterly review.

A server callback is delivered more than once.

Order confirmation is idempotent on the transaction reference. Duplicate callbacks are normal gateway behaviour and produce double fulfilment in any implementation that assumes otherwise.

A payment succeeds at PayTabs while the callback to the Worker fails.

A reconciliation job queries transaction status for anything pending past a threshold. Without it, a customer has paid and the order sits unfulfilled with no signal to anyone.

A customer in an unsupported market reaches checkout.

Market eligibility is checked before the payment is created, not after. Discovering it at the gateway produces a decline the customer reads as a card problem and blames you for.

Availability in the UAE and the wider GCC

United Arab Emirates

Well established, with AED settlement to a local account. Comparable to Telr for a single-country UAE business; the multi-country case is where PayTabs pulls ahead.

Saudi Arabia

Strong coverage including local scheme support. For a Saudi-facing bot, offering the local method is not a nicety — omitting it measurably reduces completion.

Egypt, Jordan and other regional markets

Coverage exists and varies. Each is a separate profile with its own onboarding, and each should be confirmed directly rather than assumed from regional presence.

Crypto and virtual assets

Not underwritten, as with conventional gateways generally. A virtual asset business needs TON, USDT or another chain rail rather than a card processor.

When not to use this integration

You operate in exactly one country and have no plan to expand. The multi-profile machinery is the reason to choose PayTabs, and paying for it unused is just complexity.
You have no entity in the markets you want to sell into. A merchant profile requires a local presence, and there is no way to serve a market from a neighbouring entity.
You are selling virtual assets. Card gateways do not underwrite the category, regardless of provider.
Your customers are all in Telegram buying digital goods. Stars will convert better and skip the merchant account entirely.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Per-market credential selection and server-side gateway calls.
Cloudflare D1	current	Orders keyed by market, with the resolved profile recorded.
Zod	4.4	Validation of callbacks, which differ subtly between profiles.
grammY	1.45	Checkout hand-off and the return-to-chat confirmation.

Questions that come up during scoping

Does one PayTabs relationship cover every GCC country?

One commercial relationship, yes; one merchant account, no. Each country is a separate profile with its own credentials, currency and settlement, and the bot selects between them per transaction. Treating that as configuration rather than as logic is the most common mistake here.

How does this compare to Telr for a UAE-only business?

Closely. Both settle AED locally and both underwrite UAE entities. If you will never sell outside the UAE, choose on commercial terms and support quality rather than on features, because the technical difference is small.

What happens if the wrong country profile is used?

The payment succeeds into the wrong account and nothing errors, which is why profile resolution is logged on every transaction. It is the failure mode most likely to go unnoticed and the one reconciliation is specifically designed to surface.

Should we offer local payment methods per country?

Yes. Omitting a widely used local scheme measurably reduces completion in that market, and offering a uniform international checkout everywhere means offering a worse one somewhere. The checkout differs by market on purpose.

Can we report across all countries in one currency?

Only with an explicit conversion policy, and it should be stated rather than implied. A report that adds SAR to AED because both are numbers is a quiet error that can survive several reporting cycles.

How long does onboarding take?

Per country, and it is the timeline driver rather than the build. Starting onboarding for every market you intend to serve before commissioning the bot is the single most useful thing you can do for the schedule.