Laravel BTCPay

Laravel BTCPay enables you and your business to transact in Bitcoin, Litecoin and 10+ other BTCPay-supported cryptocurrencies within your Laravel application.

Contents

• Installation
  • Install Package
  • Publish config file
  • Add configuration values
  • Interaction with API
  • Webhooks
    • 1. Use package route or define your own
    • 2. Setup your webhook listener
• Credits
• License

Installation

Requirements

• PHP 8.1 or higher
• Laravel 10 or higher

Install package

You can install the package via composer:

composer require petzsch/laravel-btcpay

Publish config file

Publish config file with:

php artisan vendor:publish --provider="Petzsch\LaravelBtcpay\BTCPayServiceProvider"

This will create a btcpay.php file inside your config directory.

Add configuration values

Add the following keys to your .env file and update the values to match your preferences (read more about configuration):

BTCPAY_API_KEY=YourRandomApiKeyThatYouOptainedFromYourBTCPayUserSettings
BTCPAY_SERVER_URL=https://btcpay.your.server.tld
BTCPAY_WEBHOOK_SECRET=YourRandomWebhookSecretString
# Optional, only if you want to use shorthand methods
BTCPAY_STORE_ID=YourBtcPayStoreId

Interaction with API

This package is wrapping the BTCPay Greenfield PHP SDK, so you can use all features provided by the SDK. You can access the endpoint clients via the BTCPay facade. For example, to access the Invoice endpoint client, you can use:

use Petzsch\LaravelBtcpay\Support\BTCPay;
use BTCPayServer\Util\PreciseNumber;

/** @var \BTCPayServer\Client\Invoice $invoiceClient */
$invoiceClient = BTCPay::invoice();

$invoiceClient->createInvoice(
    storeId: 'your-store-id',
    currency: 'USD',
    amount: new \BTCPayServer\Util\PreciseNumber('100.00'),
);

// or use the shorthand method provided by the package

$invoice = BTCPay::createInvoice(
    amount: 100.00,
    currency: 'USD',
);

Webhooks

BTCPay resource status updates are completely based on webhooks (IPNs). Laravel BTCPay fully capable of automatically handling webhook requests. Whenever a webhook is received from BTCPay's server, \Petzsch\LaravelBtcpay\Events\WebhookReceived event is dispatched. Take the following steps to configure your application for webhook listening:

1. Use package route or define your own

By default, package provides a btcpay/webhook route that will listen for incoming webhook POST requests from BTCPay's server. It automatically verifies the request signature and dispatch event only if it is valid. You can change the default route path in the btcpay.php config file by updating the webhook.prefix key.

ℹ️ To retrieve webhook route anywhere in your application, use: route('btcpay.webhook')

Alternatively, you can disable the package route by setting webhook.prefix to false in the btcpay.php config file and define your own route in your routes/web.php or routes/api.php file:

use Petzsch\LaravelBtcpay\Http\Controllers\WebhookController;

Route::post('/your-custom-webhook-path', [WebhookController::class, 'handle'])
    ->name('btcpay.webhook')
    ->middleware(\Petzsch\LaravelBtcpay\Http\Middleware\ValidateWebhookSignature::class);

2. Setup your webhook listener

Start by generating an event listener:

php artisan make:listener BTCPayWebhookListener --event=\Petzsch\LaravelBtcpay\Events\WebhookReceived

Then, implement your application-specific logic in the handle(...) function of the generated listener.

use Petzsch\LaravelBtcpay\Events\WebhookReceived;
use Petzsch\LaravelBtcpay\Enums\WebhookType;
use Illuminate\Support\Arr;

public function handle(WebhookReceived $event): void
{
    match($event->webhook->type) {
        WebhookType::InvoiceSettled => $this->handleInvoiceSettled($event),
        // handle other webhook types...
        default => null,
    };
}

protected function handleInvoiceSettled(WebhookReceived $event): void
{
    // do something with the settled invoice
}

Credits

• Vaibhavraj Roham
• Alex Stewart
• Markus Petzsch
• 021

License

The MIT License (MIT). Please see License File for more information.