Krypto-Zahlungen in Laravel empfangen (Tron)
Schritt-für-Schritt-Anleitung: ein Laravel-Zahlungsgateway für TRX und TRC20-Token mit einer Adresse pro Sitzung, Chaingateway-Webhook und Signaturprüfung.
Geprüft von Maurice Sobiera
Ein Laravel-Krypto-Zahlungsgateway erzeugt pro Zahlungssitzung eine Blockchain-Adresse, registriert auf dieser Adresse einen Webhook und markiert die Sitzung als bezahlt, sobald eine verifizierte Benachrichtigung eintrifft. Diese Anleitung baut diesen Ablauf für TRX und den Token JST (TRC20) auf Tron mit der Chaingateway-API. Der Code ist eine Demo und kein Produktivsystem.
Dasselbe Muster funktioniert für Bitcoin, Ethereum, BNB Smart Chain und Polygon, mit kleinen Änderungen an den Endpunkten. Den Demo-Code finden Sie im Repository chaingateway-crypto-payment-demo-laravel.
Verwenden Sie diesen Code nicht in der Produktion. Die Demo speichert private Schlüssel im Klartext, und das darf in einer Produktivumgebung niemals passieren. Chaingateway kann außerdem passwortgeschützte Adressen erzeugen. Dabei senden Sie ein
password, anstatt einen privaten Schlüssel zu speichern.
Was baut die Anleitung?
Das Ergebnis ist ein kleines Zahlungsgateway mit diesen Teilen:
- Ein Formular, das eine Zahlungssitzung mit einem Betrag und einer Währung (TRX oder JST) startet.
- Eine neue Wallet-Adresse für jede Sitzung.
- Eine Sitzungsseite, die Adresse, Status, erwarteten Betrag und empfangenen Betrag anzeigt.
- Einen Webhook-Endpunkt, der die Signatur prüft, die Transaktion kontrolliert, die Sitzung aktualisiert und optional die Mittel an eine Cold Wallet weiterleitet.
Wie bekomme ich einen API-Key?
Sie erstellen einen API-Token im Account-Panel von Chaingateway. Melden Sie sich auf app.chaingateway.io an, öffnen Sie die Benutzereinstellungen und wählen Sie API Tokens. Klicken Sie auf Create Token, geben Sie ihm einen Namen, etwa „Payment Gateway“, und kopieren Sie den Wert. Jede Anfrage sendet ihn als Bearer-Token. Das Entwicklerportal und die API-Referenz beschreiben die Endpunkte im Detail.
Außerdem brauchen Sie ein Laravel-Projekt mit einer konfigurierten Datenbank. Folgen Sie der Laravel-Installationsanleitung, wenn Sie bei null anfangen. Grundkenntnisse zu Models, Migrationen, Controllern und Routen reichen aus.
Schritt 1: Wie konfiguriere ich den API-Client?
Tragen Sie die Basis-URL, den Token, das Netzwerk und Ihre Cold-Wallet-Adresse in config/app.php ein. Der Header X-Network wählt das Netzwerk: testnet für die Entwicklung und mainnet für den Produktivbetrieb.
'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'),],Ergänzen Sie danach die Werte in Ihrer .env-Datei:
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_secretDas Webhook-Secret ist das persönliche Secret aus Ihren Profileinstellungen bei Chaingateway. Sobald Sie es setzen, trägt jeder Webhook einen X-Signature-Header, den Schritt 4 prüft.
Schritt 2: Wie definiere ich die Routen?
Vier Routen decken den Ablauf ab: die Zahlungsseite, den Start einer Sitzung, die Sitzungsansicht und den Webhook-Empfänger. Ergänzen Sie sie in routes/web.php. Die Webhook-Route braucht einen Namen, weil der Controller ihre URL mit route('handleWebhook') baut.
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 lehnt POST-Anfragen ohne CSRF-Token ab, und Chaingateway kann keinen senden. Schließen Sie die Webhook-Route deshalb in bootstrap/app.php aus. Die CSRF-Dokumentation von Laravel beschreibt dieselbe Einstellung für ältere Versionen.
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();Ihre Webhook-URL muss aus dem öffentlichen Internet erreichbar sein. Stellen Sie während der lokalen Entwicklung den Dev-Server über einen Tunnel bereit.
Schritt 3: Welche Models und Migrationen brauche ich?
Sie brauchen zwei Tabellen: Wallets mit ihren Schlüsseln und Zahlungssitzungen mit ihrem Status. Erzeugen Sie beide Models mit Migrationen.
php artisan make:model Wallet -mphp artisan make:model PaymentSession -mIn 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();});In 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();});Führen Sie php artisan migrate aus. Machen Sie danach die Felder befüllbar und definieren Sie die Beziehungen.
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); }}Schritt 4: Wie arbeitet der PaymentController?
Der Controller erstellt die Wallet, registriert den Webhook und verarbeitet eingehende Benachrichtigungen. Erzeugen Sie ihn mit php artisan make:controller PaymentController.
Das Anlegen einer Sitzung löst zwei API-Aufrufe aus. POST /api/v2/tron/addresses liefert eine neue Adresse und, ohne Passwort, deren privaten Schlüssel. POST /api/v2/tron/webhooks registriert einen Webhook für eingehende Transaktionen an diese Adresse und gibt die Webhook-ID in data.webhook zurück.
Der Webhook-Handler führt vier Schritte in dieser Reihenfolge aus. Er prüft den Header X-Signature. Er sucht die Sitzung anhand der empfangenden Adresse. Er fragt die API nach der Transaktion und prüft, dass ret[0].contractRet den Wert SUCCESS hat. Erst danach aktualisiert er die Sitzung.
<?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); }}Die Prüfung auf Pending schützt vor einer wiederholten Benachrichtigung, die entstehen kann, wenn Sie eine fehlgeschlagene erneut senden. Eine Benachrichtigung, die Ihr Server nicht annimmt, wird nicht automatisch wiederholt. Sie erscheint in der Liste der fehlgeschlagenen Benachrichtigungen unter GET /api/v2/tron/webhooks/notifications/failed, und Sie können sie mit POST /api/v2/tron/webhooks/notifications/{id}/retry erneut senden.
Wie prüfe ich die Webhook-Signatur?
Berechnen Sie einen HMAC-SHA256 über die txid mit Ihrem persönlichen Secret und vergleichen Sie ihn mit dem Header X-Signature. Der Header enthält das Base64-kodierte Ergebnis. HMAC ist in RFC 2104 festgelegt. Die Methode signatureIsValid oben setzt das mit hash_hmac um und vergleicht mit hash_equals, das zeitkonstant arbeitet. Die Signatur-Dokumentation enthält dieselbe Prüfung in anderen Sprachen.
Die Demo lehnt jede Benachrichtigung ab, wenn kein Secret konfiguriert ist. Eine Anfrage ohne gültige Signatur kann von jedem stammen, der Ihre Webhook-URL kennt. Verzichten Sie deshalb nicht auf die Prüfung.
Schritt 5: Wie baue ich die Views?
Zwei Blade-Views genügen: ein Formular zum Starten einer Sitzung und eine Seite, die ihren Zustand zeigt. In 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>In einem echten Shop startet der Checkout die Sitzung, nicht ein Formular. Die Sitzungsseite unten zeigt Adresse und Status. Eine echte Seite würde den Status per Polling oder WebSockets aktualisieren. In 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>Schritt 6: Wie teste ich den Ablauf?
Testen Sie zuerst im Testnetz. Starten Sie den Server mit php artisan serve und folgen Sie dann diesen Schritten.
- Öffnen Sie
/paymentund starten Sie eine neue Sitzung. - Senden Sie Testnetz-Guthaben an die Wallet-Adresse auf der Sitzungsseite.
- Warten Sie auf den Webhook oder senden Sie selbst eine signierte Benachrichtigung an
/webhook. - Laden Sie die Sitzungsseite neu und prüfen Sie, dass sich der Status geändert hat.
Um eine Benachrichtigung zu simulieren, senden Sie eine Payload wie in der Webhook-Dokumentation mit einem gültigen Header X-Signature. Denken Sie daran: Die Transaktionsprüfung fragt die API nach der txid ab. Eine erfundene Transaktions-ID endet deshalb im Status Failed.
Was sollte ich vor dem Produktivbetrieb ergänzen?
Ersetzen Sie die Abkürzungen der Demo, bevor Sie echte Zahlungen annehmen.
- Erzeugen Sie Adressen mit Passwort, damit kein privater Schlüssel in Ihrer Datenbank liegt.
- Schreiben Sie eine Zahlung erst gut, wenn die Anzahl der Bestätigungen erreicht ist, die Ihre Risikorichtlinie verlangt.
- Vergleichen Sie Beträge in der kleinsten Einheit des Tokens und prüfen Sie für jeden Token die Contract-Adresse.
- Gleichen Sie offene Sitzungen regelmäßig mit der API ab, weil ein Webhook verloren gehen kann.
Für den Einzahlungsablauf im Detail lesen Sie wie Krypto-Zahlungs-Webhooks funktionieren und Zustellungsgarantien von Webhooks. Bei Fragen hilft die Support-Seite.
Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Tron-API für die vollständige Endpoint-Referenz.