Knowledge Base
  1. Home
  2. Knowledge Base
  3. Developer guides
Developer guides

Accept crypto payments in Laravel (paygate-laravel)

Add Bitcoin, USDT, Monero and XRP to a Laravel 10 to 13 app: wallets in .env, a hosted or on-page checkout, and a middleware that rejects unsigned callbacks.

3 min readUpdated Intermediate
On this page
  1. Install and configure
  2. The callback route
  3. Checkout: hosted multi-coin page
  4. Checkout: one coin on your own page
  5. The controller
  6. Frequently asked questions

The paygate-laravel package wires the PHP SDK into Laravel: a PayGate facade configured from .env, a paygate.callback middleware that answers 403 to anything not signed by PayGate.to, and a paygate_callback_url() helper that adds a tamper-proof order token. It needs PHP 8.1+ and Laravel 10, 11, 12 or 13.

Install and configure

bash
composer require paygate-to/paygate-laravel
php artisan vendor:publish --tag=paygate-config   # optional
dotenv
APP_URL=https://shop.example8585859.com           # your public https address: callbacks are checked against it

PAYGATE_EVM_WALLET=0xYourEvmWallet               # ETH, USDT and USDC on EVM networks
PAYGATE_BTC_WALLET=bc1qYourBitcoinWallet
PAYGATE_SOLANA_WALLET=YourSolanaWallet
PAYGATE_TRC20_WALLET=TYourTronAddress
PAYGATE_XMR_WALLET=8YourMoneroSubaddress
PAYGATE_XRP_WALLET=rYourXrpAddress?dt=777         # or an X-address
# PAYGATE_LTC_WALLET, PAYGATE_BCH_WALLET, PAYGATE_DOGE_WALLET, PAYGATE_ZEC_WALLET, PAYGATE_TON_WALLET

Use self-custodial wallets: Best wallet for receiving payouts. If you published the config before XRP support, add 'xrp' => env('PAYGATE_XRP_WALLET'), to wallets in config/paygate.php.

The callback route

php
// routes/web.php
Route::get('/paygate/callback', PayGateCallbackController::class)
    ->name('paygate.callback')
    ->middleware('paygate.callback:order');

The middleware checks the RSA signature over APP_URL + path + the query string exactly as received, and with :order it also checks the order token. Your controller only runs for genuine callbacks.

Checkout: hosted multi-coin page

php
use PayGate\Laravel\Facades\PayGate;

$wallets = array_filter(config('paygate.wallets'),
    fn ($wallet, $network) => $network !== 'usdc_polygon' && $wallet, ARRAY_FILTER_USE_BOTH);

$hosted = PayGate::crypto()->createHostedWallet(
    $wallets, $order->total, $order->currency,
    paygate_callback_url('paygate.callback', ['order' => $order->id])
);

return redirect()->away(PayGate::crypto()->hostedPaymentUrl($hosted, true));   // customer pays the network fee

The customer picks any coin of the networks you configured. More in Build a hosted multi-coin checkout.

Checkout: one coin on your own page

php
$callback = paygate_callback_url('paygate.callback', ['order' => $order->id]);
$wallet   = PayGate::crypto()->createWallet('trc20_usdt', config('paygate.wallets.trc20'), $callback);
$quote    = PayGate::crypto()->convert('trc20_usdt', $order->total, $order->currency);
$qr       = PayGate::crypto()->qrCode('trc20_usdt', $wallet->getAddressIn(), $quote['value']);

$order->update(['pay_address' => $wallet->getAddressIn(), 'expected_coin' => $quote['value']]);

return view('pay', ['address' => $wallet->getAddressIn(), 'amount' => $quote['value'], 'qr' => $qr['data_uri']]);

The controller

php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;

final class PayGateCallbackController
{
    public function __invoke(Request $request)
    {
        /** @var \PayGate\Callback\CallbackData $data */
        $data = $request->attributes->get('paygate');     // set by the middleware

        if ($data->isPending()) {
            return response('ok');                         // seen, not yet confirmed
        }

        DB::transaction(function () use ($data) {
            $order = Order::lockForUpdate()->findOrFail($data->get('order'));

            // Callbacks repeat until you answer ok: credit each transaction once
            if ($order->payments()->where('txid_in', $data->getTxidIn())->exists()) {
                return;
            }
            $order->payments()->create([
                'txid_in' => $data->getTxidIn(),
                'coin'    => $data->getCoin(),
                'amount'  => $data->getValueCoin(),
            ]);

            // Paid out to YOUR wallet, right coin, enough of it
            $toMe = $data->getPayoutFor((string) config('paygate.wallets.trc20'));
            $paid = $toMe !== null
                && $data->getCoin() === 'trc20_usdt'
                && (float) $order->payments()->sum('amount') >= 0.98 * (float) $order->expected_coin;

            $order->update(['status' => $paid ? 'paid' : 'needs_review']);
        });

        return response('ok');
    }
}

A unique index on payments.txid_in keeps this safe when two deliveries arrive at once. Why each check matters: Verify PayGate.to callback signatures.

Frequently asked questions

Do I need to exclude the callback from CSRF protection?

No. Callbacks are GET requests, so CSRF protection doesn't apply.

What happens if I change APP_KEY?

Order tokens are derived from PAYGATE_CALLBACK_SECRET, or from APP_KEY when that isn't set. Changing it invalidates callback URLs of unpaid orders, so set a dedicated secret.

Can I use my own parameter names in the callback?

Yes, except PayGate.to's own names (value_coin, coin, txid_in, txid_out, address_in, value_forwarded_coin, address_out, pending). The helper refuses them.

This guide is also available as Markdown for AI assistants and offline reading.