Paddle payment provider

In this page you will learn how to configure and use the Paddle as the payment provider with Spike.

Requirements

Spike v3 has been tested with and works best with Cashier (Paddle) version 2. If you are using Cashier (Stripe) in your project already, please make sure to follow the Upgrade guide (Paddle) to update it to version 2.

Using Paddle as the payment provider

In order to use Paddle as your payment provider in Spike, you need to first remove any previously installed payment providers, and then install Cashier (Paddle) composer package:

# Remove the other payment provider
composer remove laravel/cashier

# And add the Paddle payment provider
composer require laravel/cashier-paddle

Then, run the spike:install command again to set up the payment provider and add any missing environment variables.

php artisan spike:install

Then, if you have any billable models using the Opcodes\Spike\Stripe\SpikeBillable trait, replace it with the Paddle version of the trait - Opcodes\Spike\Paddle\SpikeBillable.

And lastly, run the migrations:

php artisan migrate

Set up products in Paddle

In order to sell something using Paddle as the payment provider, you will need to create the necessary products in Paddle and get their price IDs.

When defining subscriptions and products inside config/spike.php, you will notice a key named payment_provider_price_id, which refers to the price ID of a Paddle product.

First, create the necessary products in the Paddle Products page. When creating products, you will also create prices at the same time. For regular one-time products, there's usually just one price. But for subscriptions you want to create two prices - monthly and yearly (billed once per year).

Once you have created the products and their prices, copy the price IDs (e.g. pri_01hmgp...) over to the Spike configuration in config/spike.php.

Verifying Paddle product setup

Spike has a helper command to help you verify whether your configured products and subscriptions have the correct associated payment_provider_price_ids configured. Just run this command:

php artisan spike:verify

Paddle-specific configuration

Spike itself does not currently have any configuration options for the Paddle payment provider. It works largely on its own inside the popup modal when the user wants to purchase something. Any future configuration options will be added here.

You may check out the config/cashier.php configuration for Cashier (Paddle) for any configuration options available via the Cashier package, but generally nothing there needs to be changed for Spike to work properly.

Paddle webhooks

When using the Paddle payment provider, webhooks are necessary to get notified about payment statuses to confirm of a successful payment, subscription changes, and other useful notifications.

In order for Spike to work correctly with the Paddle payment provider, you should set up Paddle Notifications to be sent to your application's /paddle/webhook URI. When setting up the notifications, make sure to select the following events:

• customer.updated
• transaction.updated
• transaction.paid
• transaction.completed
• subscription.created
• subscription.updated
• subscription.activated
• subscription.paused
• subscription.canceled

Webhooks and CSRF protection

Since Paddle webhooks need to bypass Laravel's CSRF protection, be sure to list the URI as an exception in your App\Http\Middleware\VerifyCsrfToken middleware or list the route outside the web middleware group:

protected $except = [
    'paddle/*',
];

Webhooks and local development

For Paddle to be able to send your application webhooks during local development, you will need to expose your application via a site sharing service such as Ngrok or Expose.

Verifying webhook signatures

To secure your webhooks, you may use Paddle's webhook signatures. For convenience, Spike uses Cashier (Paddle) and automatically includes a middleware which validates that the incoming Paddle webhook request is valid.

To enable webhook verification, ensure that the PADDLE_WEBHOOK_SECRET environment variable is set in your application's .env file. The webhook secret may be retrieved from your Paddle account dashboard.