Download the PHP package tigusigalpa/telegram-wallet-php without Composer
On this page you can find all versions of the php package tigusigalpa/telegram-wallet-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download tigusigalpa/telegram-wallet-php
More information about tigusigalpa/telegram-wallet-php
Files in tigusigalpa/telegram-wallet-php
Package telegram-wallet-php
Short Description Complete PHP SDK for Telegram Wallet Pay API v1.2.0 with first-class Laravel support
License MIT
Informations about the package telegram-wallet-php
Telegram Wallet Pay PHP SDK

Accept crypto payments in your PHP app or Laravel project. This SDK wraps the Telegram Wallet Pay API, letting your users pay with TON, USDT, BTC, and NOT — right inside Telegram.
Why This Package?
Building a Telegram bot with payments? We've got you covered:
- Laravel-first — Service Provider, Facade, Middleware out of the box
- Works anywhere — Use standalone in any PHP 8.1+ project
- Secure webhooks — HMAC-SHA256 signature verification built-in
- Type-safe — Modern PHP with enums, DTOs, and typed exceptions
- Tested — Comprehensive test suite you can trust
Installation
Install via Composer:
Requirements
- PHP 8.1 or higher
ext-jsonextension- Laravel 9.x, 10.x, 11.x, 12.x, or 13.x (optional, for Laravel integration)
Quick Start
Here's how simple it is to create a payment:
With Laravel
Using Laravel? It's even cleaner with the Facade:
Handling Webhooks
When a payment succeeds (or fails), Wallet Pay will notify your server:
Configuration
The defaults work great for most cases. Here's how to customize if needed:
Laravel Configuration
Publish the configuration file:
Edit config/walletpay.php:
Add to your .env:
API Reference
Here's everything you can do with the client:
| Method | What it does |
|---|---|
createOrder($request) |
Create a new payment order |
getOrderPreview($orderId) |
Check order status |
getOrderList($offset, $count) |
List orders (paginated, max 10,000) |
getOrderAmount() |
Get total order count |
Order Parameters
| Parameter | Required | What it's for |
|---|---|---|
amount |
Yes | How much to charge (e.g., new MoneyAmount('USD', '9.99')) |
description |
Yes | What the user sees (5-100 chars) |
externalId |
Yes | Your order ID — use this to match payments |
timeoutSeconds |
Yes | How long the order stays valid (30s to 10 days) |
customerTelegramUserId |
Yes | Only this Telegram user can pay |
autoConversionCurrency |
No | Convert payment to TON/USDT/BTC/NOT (+1% fee) |
returnUrl |
No | Where to send user after payment |
failReturnUrl |
No | Where to send user if payment fails |
customData |
No | Your metadata — comes back in webhooks |
Currencies
For pricing: USD, EUR
For receiving: TON, USDT, BTC, NOT
Order Lifecycle
| Status | Meaning |
|---|---|
ACTIVE |
Waiting for payment |
PAID |
Payment received! 🎉 |
EXPIRED |
Time ran out |
CANCELLED |
User or system cancelled |
Webhook Events
ORDER_PAID— Money's in! Time to deliver.ORDER_FAILED— Something went wrong (expired, cancelled, etc.)
Setting Up Webhooks
Webhooks tell you when payments happen. Here's how to set them up properly.
Step 1: Configure Your URL
In your Wallet Pay store settings, set the webhook URL:
Important:
- Must be HTTPS with a real SSL certificate (Let's Encrypt works great)
- Self-signed certs won't work
- Always return HTTP 200 to confirm receipt
Step 2: Allowlist Wallet Pay IPs
If you have a firewall, allow these IPs:
188.42.38.156172.255.249.124
Step 3: Handle Duplicate Webhooks
Wallet Pay might send the same webhook multiple times (network issues happen). Use eventId to avoid processing
duplicates:
How Signature Verification Works
You don't need to implement this yourself (our WebhookVerifier handles it), but here's what happens under the hood:
Heads up: The URI path must match exactly what you configured — including the trailing slash (or lack thereof).
Laravel Deep Dive
Service Provider
The package auto-registers — no setup needed! But if you need manual registration:
Facade
Webhook Middleware
We include middleware that verifies webhook signatures for you. Register it in app/Http/Kernel.php:
Simple Route Example
Full Controller Example
Here's a production-ready controller with payment creation and webhook handling:
When Things Go Wrong
Errors are typed, so you can handle them gracefully:
| Exception | What happened |
|---|---|
InvalidRequestException |
Bad request (check your parameters) |
InvalidApiKeyException |
Invalid API key |
OrderNotFoundException |
Order doesn't exist |
RateLimitException |
Slow down! Too many requests |
ServerException |
Wallet Pay is having issues |
InvalidWebhookSignatureException |
Webhook signature doesn't match |
Example
Things to Know
Opening the Payment Link
The payment link (directPayLink) needs to be opened correctly:
✅ In a Telegram Web App: Use Telegram.WebApp.openTelegramLink(url)
✅ In a bot message: Use it as an Inline Button URL
❌ Don't use: openLink() or MenuButtonWebApp — payment will fail
Payment Button Text
Telegram requires specific button text:
👛 Wallet Pay👛 Pay via Wallet
Yes, the purse emoji is mandatory. 👛
Preventing Duplicate Orders
Use externalId as your idempotency key. If you retry with the same ID, you'll get the existing order back:
Auto-Conversion Fees
Want to receive payments in a specific crypto? Set autoConversionCurrency, but note:
- 1% fee applies
- Minimum: $1.30 (or $3 for BTC)
When Can You Withdraw?
Funds are held for 48 hours after payment before you can withdraw them. This is a Wallet Pay policy.
One User Per Order
Only the Telegram user specified in customerTelegramUserId can pay that order. This prevents payment link sharing.
Testing
What's Next?
This package is built to grow. The architecture separates payment functionality from future trading features (spot trading, tokenized stocks, perpetual futures). When Wallet adds new APIs, we'll add support without breaking your existing code.
Contributing
Found a bug? Have an idea? PRs are welcome!
- Fork it
- Create your branch (
git checkout -b fix/something) - Make your changes
- Run tests (
vendor/bin/phpunit) - Open a PR
Please follow PSR-12 and include tests for new features.
License
MIT — do whatever you want with it.
Links
Need Help?
Open an issue on GitHub — I'll do my best to help.
Built by Igor Sazonov