The Paddle Payment Gateway add-on accepts payments through Paddle’s merchant-of-record platform — customers pay via an embedded checkout overlay powered by Paddle.js v2, while Paddle handles tax compliance, invoicing, and global payment methods in 200+ countries.
Pricing: This is a paid add-on, available from the Larapen Marketplace.
Key Features
- Paddle.js v2 checkout overlay — Customers pay via Paddle’s embedded overlay directly on your site. No redirect away from your checkout page. Supports credit/debit cards, PayPal, Apple Pay, Google Pay, and local payment methods.
- Merchant of record — Paddle acts as the merchant of record, handling VAT/sales tax collection and compliance worldwide. You receive net payouts.
- Webhook-driven confirmation — Order status updates are confirmed via signed webhooks (HMAC-SHA256) for reliable payment processing, even if the customer closes their browser.
- Refund support — Process full or partial refunds directly from the admin panel via the Paddle Adjustments API. Refund statuses (approved, pending, rejected) are tracked automatically.
- Encrypted credentials — API key, client-side token, and webhook secret are encrypted at rest using Laravel’s
Crypt::encryptString(). Never stored in plain text. - Sandbox and production — Switch between Paddle sandbox and production environments from the admin panel. Sandbox tokens start with
test_, live tokens start withlive_. - Customer linking — Stores Paddle customer IDs linked to user accounts for repeat purchases.
- Payment gateway contract — Implements the Larapen
PaymentGatewayInterface, integrating seamlessly with the E-Shop checkout flow.
Admin Panel
| Section | Description |
|---|---|
| Settings | Configure Paddle API key, client-side token, webhook secret, seller ID, environment (sandbox/production), and currency. All sensitive credentials stored encrypted. |
Payment Flow
- Customer selects “Paddle” at checkout. An informational message appears.
- Form is submitted via AJAX. The server creates a Paddle transaction via the API.
- Paddle.js overlay opens with
Paddle.Checkout.open()using the transaction ID. - Customer completes payment within the overlay (cards, PayPal, Apple Pay, etc.).
- On
checkout.completed, the customer is redirected to the return URL for confirmation. - Paddle also sends a
transaction.completedwebhook as a reliable backup.
Webhook Events
| Event | Action |
|---|---|
transaction.completed | Marks the order as paid and creates a shop transaction record. |
transaction.payment_failed | Marks the payment as failed with error code. |
adjustment.created | Updates order status to refunded if the adjustment is an approved refund. |
adjustment.updated | Same handling as adjustment.created for refund status changes. |
Configuration
| Setting | Description |
|---|---|
| API Key | Paddle API key for server-side API calls (transactions, refunds). Stored encrypted. |
| Client-Side Token | Token for initializing Paddle.js on the frontend. Sandbox tokens start with test_. Stored encrypted. |
| Webhook Secret | Secret key for verifying Paddle webhook signatures (HMAC-SHA256). Stored encrypted. |
| Seller ID | Your Paddle seller/vendor ID. Required for Paddle.js initialization. |
| Environment | sandbox for testing or production for live payments. |
| Currency | Currency code (e.g., USD, EUR, GBP). Should match your shop currency. |
Dependencies
Required: The E-Shop add-on must be installed and active. The Paddle add-on registers as a payment gateway via the PaymentGatewayInterface contract and is automatically discovered by the shop’s payment system. The paddle/paddle-php-sdk Composer package is required.
Setup Guide
- Install and activate the E-Shop add-on first.
- Install the Paddle PHP SDK:
composer require paddle/paddle-php-sdk. - Install and activate the Paddle add-on.
- Go to Paddle > Settings in the admin panel.
- Enter your API key, client-side token, and seller ID from the Paddle Dashboard.
- Create a webhook in Paddle Dashboard pointing to
https://yoursite.com/paddle/webhookand enter the webhook secret. - Paddle will appear as a payment option during checkout.
Ideal for
- SaaS businesses and digital product sellers wanting automated tax compliance.
- International e-commerce sites needing multi-currency support with automatic VAT handling.
- Businesses wanting a merchant-of-record solution that simplifies global selling.
- Sites selling to EU customers needing automated VAT MOSS compliance.