Recevoir des paiements crypto dans Laravel (Tron)
Créez une passerelle de paiement Laravel pour TRX et jetons TRC20 : une adresse par session, webhook Chaingateway, contrôle de signature et vérification.
Relu par Maurice Sobiera
Une passerelle de paiement crypto Laravel crée une adresse blockchain par session de paiement, enregistre un webhook sur cette adresse et marque la session comme payée quand une notification vérifiée arrive. Ce tutoriel construit ce flux pour le TRX et le jeton JST (TRC20) sur Tron avec l’API Chaingateway. Le code est une démo, pas un système de production.
Le même schéma fonctionne pour Bitcoin, Ethereum, BNB Smart Chain et Polygon, avec de petites adaptations des points d’accès. Le code de la démo est disponible dans le dépôt chaingateway-crypto-payment-demo-laravel.
N’utilisez pas ce code en production. La démo stocke les clés privées en texte brut, ce qui ne doit jamais arriver dans un environnement de production. Chaingateway peut aussi créer des adresses protégées par mot de passe : vous envoyez alors un
passwordau lieu de stocker une clé privée.
Que construit ce tutoriel ?
Le résultat est une petite passerelle de paiement composée des éléments suivants :
- Un formulaire qui démarre une session de paiement avec un montant et une devise (TRX ou JST).
- Une nouvelle adresse de portefeuille pour chaque session.
- Une page de session qui affiche l’adresse, le statut, le montant attendu et le montant reçu.
- Un point d’accès webhook qui vérifie la signature, contrôle la transaction, met à jour la session et, en option, transfère les fonds vers un portefeuille froid.
Comment obtenir une clé API ?
Vous créez un jeton API dans le panneau de compte Chaingateway. Connectez-vous sur app.chaingateway.io, ouvrez les paramètres utilisateur et sélectionnez API Tokens. Cliquez sur Create Token, donnez-lui un nom (par exemple « Payment Gateway ») et copiez la valeur. Chaque requête l’envoie comme jeton bearer. Le portail développeur et la référence de l’API décrivent les points d’accès en détail.
Vous avez aussi besoin d’un projet Laravel avec une base de données configurée. Suivez le guide d’installation de Laravel si vous partez de zéro. Une connaissance de base des modèles, des migrations, des contrôleurs et des routes suffit.
Étape 1 : comment configurer le client API ?
Ajoutez l’URL de base, le jeton, le réseau et l’adresse de votre portefeuille froid dans config/app.php. L’en-tête X-Network choisit le réseau : testnet pour le développement et mainnet pour la production.
'Chaingateway' => [ 'api_url' => env('Chaingateway_API_URL', 'https://app.chaingateway.io/api/v2'), 'api_key' => env('Chaingateway_API_KEY'), 'network' => env('Chaingateway_NETWORK', 'testnet'), // Use 'mainnet' for production 'cold_wallet' => env('COLD_WALLET'), 'webhook_secret' => env('Chaingateway_WEBHOOK_SECRET'),],Ajoutez ensuite les valeurs à votre fichier .env :
Chaingateway_API_URL=https://app.chaingateway.io/api/v2Chaingateway_API_KEY=your_api_key_hereChaingateway_NETWORK=testnetCOLD_WALLET=your_cold_wallet_addressChaingateway_WEBHOOK_SECRET=your_personal_secretLe secret du webhook est le secret personnel des paramètres de votre profil Chaingateway. Dès que vous le définissez, chaque webhook porte un en-tête X-Signature, que l’étape 4 vérifie.
Étape 2 : comment définir les routes ?
Quatre routes couvrent le flux : la page de paiement, le démarrage d’une session, l’affichage de la session et le récepteur de webhook. Ajoutez-les à routes/web.php. La route du webhook a besoin d’un nom, car le contrôleur construit son URL avec route('handleWebhook').
use App\Http\Controllers\PaymentController;
Route::get('/payment', [PaymentController::class, 'showPaymentPage']);Route::post('/start-payment-session', [PaymentController::class, 'startPaymentSession']);Route::get('/payment-session/{id}', [PaymentController::class, 'showPaymentSession'])->name('showPaymentSession');Route::post('/webhook', [PaymentController::class, 'handleWebhook'])->name('handleWebhook');Laravel rejette les requêtes POST sans jeton CSRF, et Chaingateway ne peut pas en envoyer. Excluez la route du webhook dans bootstrap/app.php. La documentation CSRF de Laravel décrit le même réglage pour les anciennes versions.
use Illuminate\Foundation\Application;use Illuminate\Foundation\Configuration\Exceptions;use Illuminate\Foundation\Configuration\Middleware;
return Application::configure(basePath: dirname(__DIR__)) ->withRouting( web: __DIR__.'/../routes/web.php', commands: __DIR__.'/../routes/console.php', health: '/up', ) ->withMiddleware(function (Middleware $middleware) { // Exclude the webhook route from CSRF protection $middleware->validateCsrfTokens(except: [ 'webhook', ]); }) ->withExceptions(function (Exceptions $exceptions) { // })->create();Votre URL de webhook doit être joignable depuis l’internet public. Pendant le développement local, exposez le serveur de développement par un tunnel.
Étape 3 : de quels modèles et migrations ai-je besoin ?
Vous avez besoin de deux tables : les portefeuilles avec leurs clés, et les sessions de paiement avec leur statut. Générez les deux modèles avec leurs migrations.
php artisan make:model Wallet -mphp artisan make:model PaymentSession -mDans database/migrations/<timestamp>_create_wallets_table.php :
Schema::create('wallets', function (Blueprint $table) { $table->id(); $table->string('address')->unique(); // Wallet address $table->string('private_key'); // Demo only: never store keys in plain text $table->timestamps();});Dans database/migrations/<timestamp>_create_payment_sessions_table.php :
Schema::create('payment_sessions', function (Blueprint $table) { $table->id(); $table->string('status')->default('Pending'); // Pending, Completed, Failed, overpaid, underpaid $table->foreignId('wallet_id')->constrained()->onDelete('cascade'); $table->decimal('amount', 18, 8)->nullable(); // Amount the customer should send $table->string('currency')->default('TRX'); $table->decimal('received_amount', 18, 8)->nullable(); // Amount that arrived $table->string('webhook_id')->nullable(); $table->timestamps();});Exécutez php artisan migrate, puis rendez les champs remplissables et définissez les relations.
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class Wallet extends Model{ protected $fillable = ['address', 'private_key'];
public function paymentSessions() { return $this->hasMany(PaymentSession::class); }}namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class PaymentSession extends Model{ protected $fillable = ['wallet_id', 'status', 'amount', 'currency', 'received_amount', 'webhook_id'];
public function wallet() { return $this->belongsTo(Wallet::class); }}Étape 4 : comment fonctionne le PaymentController ?
Le contrôleur crée le portefeuille, enregistre le webhook et traite les notifications entrantes. Générez-le avec php artisan make:controller PaymentController.
Créer une session déclenche deux appels d’API. POST /api/v2/tron/addresses renvoie une nouvelle adresse et, sans mot de passe, sa clé privée. POST /api/v2/tron/webhooks enregistre un webhook pour les transactions entrantes vers cette adresse et renvoie l’identifiant du webhook dans data.webhook.
Le gestionnaire de webhook fait quatre choses dans l’ordre. Il vérifie l’en-tête X-Signature. Il cherche la session à partir de l’adresse de réception. Il demande la transaction à l’API et vérifie que ret[0].contractRet vaut SUCCESS. Ce n’est qu’alors qu’il met à jour la session.
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Client\PendingRequest;use Illuminate\Http\Request;use Illuminate\Support\Facades\Http;use App\Models\PaymentSession;use App\Models\Wallet;
class PaymentController extends Controller{ private $apiUrl; private $apiKey; private $network; private $coldWallet; private $webhookSecret;
public function __construct() { $this->apiUrl = config('app.Chaingateway.api_url'); $this->apiKey = config('app.Chaingateway.api_key'); $this->network = config('app.Chaingateway.network'); $this->coldWallet = config('app.Chaingateway.cold_wallet'); $this->webhookSecret = config('app.Chaingateway.webhook_secret'); }
private function api(): PendingRequest { return Http::withHeaders([ 'Authorization' => "Bearer {$this->apiKey}", 'Content-Type' => 'application/json', 'X-Network' => $this->network, ]); }
public function showPaymentPage() { return view('payment'); }
/** * Creates a wallet address and a webhook for it, then stores the session. */ public function startPaymentSession(Request $request) { $validated = $request->validate([ 'amount' => 'required|numeric|gt:0', 'currency' => 'required|in:TRX,JST', ]);
$response = $this->api()->post("{$this->apiUrl}/tron/addresses");
if (! $response->successful()) { return back()->withErrors(['error' => 'Failed to create payment session.']); }
$walletData = $response->json()['data'];
$wallet = Wallet::create([ 'address' => $walletData['address'], 'private_key' => $walletData['privateKey'], ]);
$webhookResponse = $this->api()->post("{$this->apiUrl}/tron/webhooks", [ 'to' => $wallet->address, 'url' => route('handleWebhook'), ]);
if (! $webhookResponse->successful()) { return back()->withErrors(['error' => 'Failed to create webhook.']); }
$paymentSession = PaymentSession::create([ 'wallet_id' => $wallet->id, 'webhook_id' => $webhookResponse->json()['data']['webhook'], 'amount' => $validated['amount'], 'currency' => $validated['currency'], 'status' => 'Pending', ]);
return redirect()->route('showPaymentSession', ['id' => $paymentSession->id]); }
public function showPaymentSession($id) { $paymentSession = PaymentSession::with('wallet')->findOrFail($id); return view('payment-session', compact('paymentSession')); }
public function handleWebhook(Request $request) { $transactionData = $request->all();
// 1. Verify that Chaingateway sent the notification (see the signature section) if (! $this->signatureIsValid($transactionData['txid'] ?? '', $request->header('X-Signature', ''))) { return response()->json(['error' => 'Invalid signature'], 401); }
// 2. Find the session for the receiving address $wallet = Wallet::where('address', $transactionData['to'])->first(); if (! $wallet) { return response()->json(['error' => 'Wallet not found'], 404); }
$paymentSession = PaymentSession::where('wallet_id', $wallet->id)->first(); if (! $paymentSession) { return response()->json(['error' => 'Payment session not found'], 404); }
// A notification can arrive twice. Acknowledge it without processing it again. if ($paymentSession->status !== 'Pending') { return response()->json(['status' => 'already processed']); }
// 3. Check on chain that the transaction succeeded $txResponse = $this->api()->get("{$this->apiUrl}/tron/transactions/{$transactionData['txid']}"); $contractRet = $txResponse->json('data.transaction.ret.0.contractRet');
if ($txResponse->successful() && $contractRet === 'SUCCESS') { $paymentSession->status = 'Completed'; $paymentSession->received_amount = $transactionData['amount'];
// Compare the received amount with the expected one and allow a margin. // Check in a test notification whether `amount` is in the token's smallest unit // or already a decimal value, and convert before you compare. $allowedDifference = $paymentSession->amount * 0.10; if (abs($paymentSession->amount - $transactionData['amount']) >= $allowedDifference) { $paymentSession->status = $transactionData['amount'] > $paymentSession->amount ? 'overpaid' : 'underpaid'; }
// For tokens, check that the contract is the one you expect (JST on Tron mainnet) if ($paymentSession->currency == 'JST' && ($transactionData['contractaddress'] ?? null) != 'TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3') { $paymentSession->status = 'Wrong currency received'; }
/** * Optional: forward the funds to a cold wallet. * A TRC20 transfer needs Energy, so the address must hold TRX or staked resources. * Chaingateway's Tron Paymaster is deprecated. Use TronFuel (https://tronfuel.dev) * if you do not want to handle the fees yourself. * * $endpoint = $transactionData['contractaddress'] * ? "{$this->apiUrl}/tron/transactions/trc20" * : "{$this->apiUrl}/tron/transactions"; * * $this->api()->post($endpoint, [ * 'amount' => $transactionData['amount'], * 'privatekey' => $wallet->private_key, * 'to' => $this->coldWallet, * 'from' => $transactionData['to'], * 'contractaddress' => $transactionData['contractaddress'], * ]); */ } else { $paymentSession->status = 'Failed'; }
// Delete the webhook if you will not reuse the address $this->api()->delete("{$this->apiUrl}/tron/webhooks/{$paymentSession->webhook_id}");
$paymentSession->save(); return response()->json(['status' => 'success']); }
private function signatureIsValid(string $txid, string $received): bool { if (! $this->webhookSecret) { return false; }
$expected = base64_encode(hash_hmac('sha256', $txid, $this->webhookSecret, true)); return hash_equals($expected, $received); }}Le contrôle Pending vous protège contre une notification répétée, ce qui peut arriver quand vous renvoyez une notification échouée. Une notification que votre serveur n’accepte pas n’est pas renvoyée automatiquement. Elle apparaît dans la liste des notifications échouées à GET /api/v2/tron/webhooks/notifications/failed, et vous pouvez la renvoyer avec POST /api/v2/tron/webhooks/notifications/{id}/retry.
Comment vérifier la signature du webhook ?
Calculez un HMAC-SHA256 sur le txid avec votre secret personnel et comparez-le à l’en-tête X-Signature. L’en-tête contient le résultat encodé en Base64. HMAC est spécifié dans la RFC 2104. La méthode signatureIsValid ci-dessus l’implémente avec hash_hmac et compare avec hash_equals, qui s’exécute en temps constant. La documentation sur la signature présente le même contrôle dans d’autres langages.
La démo rejette toutes les notifications si aucun secret n’est configuré. Une requête sans signature valide pourrait venir de n’importe qui connaissant votre URL de webhook : ne sautez donc pas ce contrôle.
Étape 5 : comment construire les vues ?
Deux vues Blade suffisent : un formulaire pour démarrer une session et une page qui affiche son état. Dans resources/views/payment.blade.php :
<!DOCTYPE html><html> <head> <title>Start Payment Session</title> </head> <body> <h2>Start a New Payment Session</h2> <form action="/start-payment-session" method="POST"> @csrf <label for="amount">Amount:</label> <input type="number" step="0.01" name="amount" id="amount" required /> <br /> <label for="currency">Currency:</label> <select name="currency" id="currency" required> <option value="TRX">TRX</option> <option value="JST">JST (TRC20)</option> </select> <br /> <button type="submit">Start Payment Session</button> </form> </body></html>Dans une vraie boutique, c’est le processus de commande qui démarre la session, pas un formulaire. La page de session ci-dessous affiche l’adresse et le statut. Une vraie page actualiserait le statut par polling ou par websockets. Dans resources/views/payment-session.blade.php :
<!DOCTYPE html><html> <head> <title>Payment Session</title> </head> <body> <h2>Payment Session</h2> <p> Send <strong>{{ $paymentSession->amount }} {{ $paymentSession->currency }}</strong> to the address below: </p> <p><strong>{{ $paymentSession->wallet->address }}</strong></p> <p>Status: <strong>{{ $paymentSession->status }}</strong></p> <p> Received: <strong>{{ $paymentSession->received_amount }} {{ $paymentSession->currency }}</strong> </p> </body></html>Étape 6 : comment tester le flux ?
Testez d’abord sur le testnet. Démarrez le serveur avec php artisan serve, puis suivez ces étapes.
- Ouvrez
/paymentet démarrez une nouvelle session. - Envoyez des fonds de testnet à l’adresse de portefeuille affichée sur la page de session.
- Attendez le webhook, ou envoyez vous-même une notification signée à
/webhook. - Rechargez la page de session et vérifiez que le statut a changé.
Pour simuler une notification, envoyez un payload comme celui de la documentation des webhooks avec un en-tête X-Signature valide. N’oubliez pas que le contrôle de transaction appelle l’API avec le txid : un identifiant de transaction inventé se termine donc par le statut Failed.
Que dois-je ajouter avant la production ?
Remplacez les raccourcis de la démo avant d’accepter de vrais paiements.
- Créez les adresses avec un mot de passe, pour qu’aucune clé privée ne soit stockée dans votre base de données.
- Ne créditez un paiement qu’après le nombre de confirmations exigé par votre politique de risque.
- Comparez les montants dans la plus petite unité du jeton et vérifiez l’adresse du contrat pour chaque jeton.
- Rapprochez régulièrement les sessions ouvertes de l’API, car un webhook peut être manqué.
Pour le flux de dépôt plus en détail, lisez comment fonctionnent les webhooks de paiement crypto et les garanties de livraison des webhooks. Pour toute question, consultez la page d’assistance.
Comment nous rédigeons ces articles
Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Tron pour la référence complète des endpoints.