Recibir pagos cripto en Laravel con Tron
Tutorial para crear una pasarela de pago en Laravel para TRX y tokens TRC20: una dirección por sesión, webhook de Chaingateway, firma y verificación.
Revisado por Maurice Sobiera
Una pasarela de pago cripto en Laravel crea una dirección de blockchain por sesión de pago, registra en ella un webhook y marca la sesión como pagada cuando llega una notificación verificada. Este tutorial lo construye para TRX y el token JST (TRC20) en Tron con la API de Chaingateway. El código es una demostración, no un sistema de producción.
El mismo patrón funciona para Bitcoin, Ethereum, BNB Smart Chain y Polygon con pequeños cambios en los endpoints. El código de la demostración está disponible en el repositorio chaingateway-crypto-payment-demo-laravel.
No utilice este código en producción. La demostración guarda las claves privadas en texto plano, algo que nunca debe ocurrir en un entorno de producción. Chaingateway también puede crear direcciones protegidas con contraseña, en las que usted envía un
passworden lugar de guardar una clave privada.
¿Qué construye el tutorial?
El resultado es una pequeña pasarela de pago con estas partes:
- Un formulario que inicia una sesión de pago con un importe y una moneda (TRX o JST).
- Una nueva dirección de wallet para cada sesión.
- Una página de sesión que muestra la dirección, el estado, el importe esperado y el importe recibido.
- Un endpoint de webhook que verifica la firma, comprueba la transacción, actualiza la sesión y, de forma opcional, reenvía los fondos a una cold wallet.
¿Cómo obtengo una clave API?
Usted crea un token de API en el panel de cuenta de Chaingateway. Inicie sesión en app.chaingateway.io, abra los ajustes de usuario y seleccione API Tokens. Haga clic en Create Token, póngale un nombre (por ejemplo “Payment Gateway”) y copie el valor. Cada solicitud lo envía como bearer token. El portal para desarrolladores y la referencia de la API describen los endpoints en detalle.
También necesita un proyecto Laravel con una base de datos configurada. Si empieza desde cero, siga la guía de instalación de Laravel. Bastan conocimientos básicos de modelos, migraciones, controladores y rutas.
Paso 1: ¿Cómo configuro el cliente de la API?
Añada la URL base, el token, la red y la dirección de su cold wallet a config/app.php. La cabecera X-Network selecciona la red: testnet para desarrollo y mainnet para producción.
'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'),],Después añada los valores a su archivo .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_secretEl secreto del webhook es el secreto personal de los ajustes de su perfil de Chaingateway. Una vez definido, cada webhook lleva una cabecera X-Signature, que el paso 4 verifica.
Paso 2: ¿Cómo defino las rutas?
Cuatro rutas cubren el flujo: la página de pago, el inicio de una sesión, la vista de la sesión y el receptor del webhook. Añádalas a routes/web.php. La ruta del webhook necesita un nombre, porque el controlador construye su URL con 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 rechaza las solicitudes POST sin token CSRF, y Chaingateway no puede enviar uno. Excluya la ruta del webhook en bootstrap/app.php. La documentación de CSRF de Laravel describe el mismo ajuste para versiones anteriores.
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();La URL de su webhook debe ser accesible desde Internet público. Durante el desarrollo local, exponga el servidor de desarrollo mediante un túnel.
Paso 3: ¿Qué modelos y migraciones necesito?
Necesita dos tablas: wallets con sus claves y sesiones de pago con su estado. Genere ambos modelos con sus migraciones.
php artisan make:model Wallet -mphp artisan make:model PaymentSession -mEn 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();});En 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();});Ejecute php artisan migrate, y después haga los campos rellenables y defina las relaciones.
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); }}Paso 4: ¿Cómo funciona el PaymentController?
El controlador crea la wallet, registra el webhook y gestiona las notificaciones entrantes. Genérelo con php artisan make:controller PaymentController.
Crear una sesión supone dos llamadas a la API. POST /api/v2/tron/addresses devuelve una dirección nueva y, sin contraseña, su clave privada. POST /api/v2/tron/webhooks registra un webhook para las transacciones entrantes a esa dirección y devuelve el ID del webhook en data.webhook.
El manejador del webhook hace cuatro cosas en orden. Verifica la cabecera X-Signature. Busca la sesión por la dirección receptora. Pide a la API la transacción y comprueba que ret[0].contractRet sea SUCCESS. Solo entonces actualiza la sesión.
<?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); }}La comprobación de Pending le protege frente a una notificación repetida, algo que puede ocurrir cuando usted reenvía una notificación fallida. Una notificación que su servidor no acepta no se reintenta automáticamente. Aparece en la lista de notificaciones fallidas en GET /api/v2/tron/webhooks/notifications/failed, y puede reenviarla con POST /api/v2/tron/webhooks/notifications/{id}/retry.
¿Cómo verifico la firma del webhook?
Calcule un HMAC-SHA256 sobre el txid con su secreto personal y compárelo con la cabecera X-Signature. La cabecera contiene el resultado codificado en Base64. HMAC está especificado en la RFC 2104. El método signatureIsValid de arriba lo implementa con hash_hmac y compara con hash_equals, que tarda un tiempo constante. La documentación de la firma muestra la misma comprobación en otros lenguajes.
La demostración rechaza todas las notificaciones si no hay un secreto configurado. Una solicitud sin firma válida podría venir de cualquiera que conozca la URL de su webhook, así que no debería omitir la comprobación.
Paso 5: ¿Cómo construyo las vistas?
Bastan dos vistas Blade: un formulario para iniciar una sesión y una página que muestre su estado. En 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>En una tienda real, el proceso de compra inicia la sesión, no un formulario. La página de sesión de abajo muestra la dirección y el estado. Una página real actualizaría el estado mediante polling o websockets. En 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>Paso 6: ¿Cómo pruebo el flujo?
Pruebe primero en la testnet. Inicie el servidor con php artisan serve y siga estos pasos.
- Abra
/paymente inicie una nueva sesión. - Envíe fondos de testnet a la dirección de la wallet que muestra la página de sesión.
- Espere al webhook, o envíe usted mismo una notificación firmada a
/webhook. - Recargue la página de sesión y compruebe que el estado ha cambiado.
Para simular una notificación, envíe un payload como el de la documentación de webhooks con una cabecera X-Signature válida. Recuerde que la comprobación de la transacción consulta a la API el txid, de modo que un ID de transacción inventado termina en el estado Failed.
¿Qué debo añadir antes de producción?
Sustituya los atajos de la demostración antes de aceptar pagos reales.
- Cree las direcciones con una contraseña para que no se guarde ninguna clave privada en su base de datos.
- Acredite un pago solo tras el número de confirmaciones que exija su política de riesgo.
- Compare los importes en la unidad mínima del token y verifique la dirección del contrato en cada token.
- Concilie con la API las sesiones abiertas de forma periódica, porque un webhook puede perderse.
Para el flujo de depósitos con más detalle, lea cómo funcionan los webhooks de pagos cripto y las garantías de entrega de webhooks. Si tiene preguntas, consulte la página de soporte.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API de Tron para la referencia completa de los endpoints.