telegram-bot-essentials/gateway-zibal

Zibal payment gateway for telegram-bot-essentials/billing

v0.0.11 2026-09-01 12:27 UTC

Requires

• php: ^8.3
• laravel/framework: ^12 || ^13
• telegram-bot-essentials/billing: ~0.0.32
• telegram-bot-essentials/essence: ^0.12
• telegram-bot-essentials/settings: ~0.0.17

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.18
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.7 || ^4.0
• pestphp/pest-plugin-laravel: ^3.1 || ^4.0

MIT

• Elyar

Published on Packagist.org on 2026-09-02 09:05 UTC

README

Integrates Zibal — an Iranian online payment gateway — with telegram-bot-essentials/billing. Unlike gateway-card, this is a fully automated, redirect-based gateway: the buyer is sent to a real payment page and the invoice is marked paid automatically via a server-to-server callback.

It's the template to follow for integrating any other redirect-based payment provider.

Installation

composer require telegram-bot-essentials/gateway-zibal
php artisan migrate

Configure per-bot via Settings:

Setting key	Type	Purpose
billing.gateways.zibal.status	CHECKBOX	Master on/off switch
billing.gateways.zibal.merchant	SENSITIVE	Zibal merchant key (encrypted at rest)

Both must be set for the gateway to appear on the invoice screen.

Flow

Zibal payment happens on Zibal's own web page, so this gateway is driven by HTTP routes, not CallbackQueries/StateAnswers:

1. Buyer taps the invoice's "Pay with Zibal" button (an external URL) → GatewayZibalController::pay() converts the price to Rial, requests a payment, creates a ToZibalAttempt, and redirects to Zibal.
2. Buyer pays on Zibal's page → Zibal redirects back to GatewayZibalController::callback(), which calls zibal()->verify() and, on success, attemptSucceed() → Invoice::markAsPaid(), then renders a "back to bot" deep link.

Because the callback arrives outside any Telegram webhook, the controller re-establishes tenancy and the webhook context before touching billing state — see the docs for the exact pattern.

Documentation

Full documentation — the Zibal service, the ToZibalAttempt model, and a side-by-side comparison with Gateway: Card — lives on the Telegram Bot Essentials documentation site under Modules → Gateway: Zibal.

License

MIT.