← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

Приём крипто-платежей в Laravel (Tron)

Платёжный шлюз на Laravel для TRX и токенов TRC20: один адрес на сессию, вебхук Chaingateway, проверка подписи и проверка транзакции.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) Maurice Sobiera

Платёжный шлюз на Laravel для криптовалют создаёт один адрес блокчейна на каждую платёжную сессию, регистрирует вебхук на этот адрес и помечает сессию как оплаченную, когда приходит проверенное уведомление. Это руководство строит такой поток для TRX и токена JST (TRC20) в Tron с помощью API Chaingateway. Код — демонстрация, а не готовая продакшн-система.

Тот же шаблон работает для Bitcoin, Ethereum, BNB Smart Chain и Polygon с небольшими изменениями endpoint-ов. Демонстрационный код доступен в репозитории chaingateway-crypto-payment-demo-laravel.

Не используйте этот код в продакшне. Демонстрация хранит закрытые ключи в открытом виде, а это в продакшне недопустимо. Chaingateway также может создавать адреса, защищённые паролем, куда вы отправляете password вместо хранения закрытого ключа.

Что строит руководство?

Результат — небольшой платёжный шлюз с такими частями:

  1. Форма, которая запускает платёжную сессию с суммой и валютой (TRX или JST).
  2. Новый адрес кошелька для каждой сессии.
  3. Страница сессии, которая показывает адрес, статус, ожидаемую сумму и полученную сумму.
  4. Endpoint вебхука, который проверяет подпись, проверяет транзакцию, обновляет сессию и при необходимости переводит средства на холодный кошелёк.

Как получить API-ключ?

Токен API создаётся в панели аккаунта Chaingateway. Войдите на app.chaingateway.io, откройте настройки пользователя и выберите «API Tokens». Нажмите «Create Token», дайте имя (например, «Payment Gateway») и скопируйте значение. Каждый запрос передаёт его как bearer-токен. Портал разработчика и справочник API подробно описывают endpoint-ы.

Также нужен проект Laravel с настроенной базой данных. Если начинаете с нуля, следуйте руководству по установке Laravel. Достаточно базового знания моделей, миграций, контроллеров и маршрутов.

Шаг 1: как настроить клиент API?

Добавьте базовый URL, токен, сеть и адрес холодного кошелька в config/app.php. Заголовок X-Network выбирает сеть: testnet для разработки и mainnet для продакшна.

'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'),
],

Затем добавьте значения в файл .env:

Chaingateway_API_URL=https://app.chaingateway.io/api/v2
Chaingateway_API_KEY=your_api_key_here
Chaingateway_NETWORK=testnet
COLD_WALLET=your_cold_wallet_address
Chaingateway_WEBHOOK_SECRET=your_personal_secret

Секрет вебхука — это персональный секрет из настроек вашего профиля Chaingateway. Как только вы его задали, каждый вебхук несёт заголовок X-Signature, который проверяется на шаге 4.

Шаг 2: как определить маршруты?

Четыре маршрута покрывают поток: страница оплаты, запуск сессии, просмотр сессии и приёмник вебхука. Добавьте их в routes/web.php. Маршрут вебхука нужно именовать, потому что контроллер строит его URL через 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 отклоняет POST-запросы без токена CSRF, а Chaingateway отправить его не может. Исключите маршрут вебхука в bootstrap/app.php. Документация Laravel по CSRF описывает ту же настройку для старых версий.

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();

URL вашего вебхука должен быть доступен из публичного интернета. При локальной разработке выведите dev-сервер через туннель.

Шаг 3: какие модели и миграции нужны?

Нужны две таблицы: кошельки с их ключами и платёжные сессии с их статусом. Создайте обе модели вместе с миграциями.

Terminal window
php artisan make:model Wallet -m
php artisan make:model PaymentSession -m

В 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();
});

В 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();
});

Выполните php artisan migrate, затем сделайте поля заполняемыми и определите связи.

app/Models/Wallet.php
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);
}
}
app/Models/PaymentSession.php
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);
}
}

Шаг 4: как работает PaymentController?

Контроллер создаёт кошелёк, регистрирует вебхук и обрабатывает входящие уведомления. Сгенерируйте его командой php artisan make:controller PaymentController.

Создание сессии делает два вызова API. POST /api/v2/tron/addresses возвращает новый адрес и, без пароля, его закрытый ключ. POST /api/v2/tron/webhooks регистрирует вебхук для входящих транзакций на этот адрес и возвращает ID вебхука в data.webhook.

Обработчик вебхука выполняет четыре действия по порядку. Он проверяет заголовок X-Signature. Ищет сессию по принимающему адресу. Запрашивает у API транзакцию и проверяет, что ret[0].contractRet равен SUCCESS. Только после этого обновляет сессию.

<?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);
}
}

Проверка Pending защищает от повторного уведомления, которое может прийти, когда вы повторно отправляете неудачное. Уведомление, которое ваш сервер не принял, автоматически не повторяется. Оно появляется в списке неудачных уведомлений по адресу GET /api/v2/tron/webhooks/notifications/failed, и его можно отправить повторно через POST /api/v2/tron/webhooks/notifications/{id}/retry.

Как проверить подпись вебхука?

Вычислите HMAC-SHA256 от txid с вашим персональным секретом и сравните его с заголовком X-Signature. Заголовок содержит результат в кодировке Base64. HMAC описан в RFC 2104. Метод signatureIsValid выше реализует это через hash_hmac и сравнивает через hash_equals, которая работает за постоянное время. Документация по подписи приводит ту же проверку на других языках.

Демонстрация отклоняет каждое уведомление, если секрет не задан. Запрос без корректной подписи может прислать любой, кто знает URL вашего вебхука, поэтому пропускать проверку не стоит.

Шаг 5: как построить представления?

Для этого достаточно двух Blade-представлений: формы для запуска сессии и страницы, которая показывает её состояние. В 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>

В реальном магазине сессию запускает процесс оформления заказа, а не форма. Страница сессии ниже показывает адрес и статус. Настоящая страница обновляла бы статус через опрос или WebSocket. В 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>

Шаг 6: как протестировать поток?

Сначала тестируйте в testnet. Запустите сервер командой php artisan serve, затем выполните шаги.

  1. Откройте /payment и запустите новую сессию.
  2. Отправьте тестовые средства testnet на адрес кошелька со страницы сессии.
  3. Дождитесь вебхука или отправьте подписанное уведомление на /webhook самостоятельно.
  4. Перезагрузите страницу сессии и убедитесь, что статус изменился.

Чтобы смоделировать уведомление, отправьте payload, похожий на описанный в документации по вебхукам, с корректным заголовком X-Signature. Помните, что проверка транзакции обращается к API за txid, поэтому выдуманный ID транзакции приведёт к статусу Failed.

Что добавить перед продакшном?

Замените демонстрационные упрощения, прежде чем принимать настоящие платежи.

  • Создавайте адреса с паролем, чтобы в вашей базе данных не хранился ни один закрытый ключ.
  • Зачисляйте платёж только после числа подтверждений, которое требует ваша политика рисков.
  • Сравнивайте суммы в наименьшей единице токена и проверяйте адрес контракта для каждого токена.
  • Регулярно сверяйте открытые сессии с API, потому что вебхук может потеряться.

Подробнее о потоке депозитов читайте как работают вебхуки для крипто-платежей и гарантии доставки вебхуков. Вопросы — на странице поддержки.

Как мы пишем эти статьи

Готовы собрать это сами? Получите свой API-ключ — 7-дневный пробный период, без карты — или посмотрите API Tron для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.