Paddle Billing: Setup and Payment Events

What Paddle handles

Paddle acts as Merchant of Record for eligible transactions processed through Paddle. Its tax and billing services apply to those transactions under your Paddle agreement; connecting a gateway does not make every part of a business compliant in every jurisdiction.

Before setup

Complete the account and product approval required by Paddle.
Use the current Paddle Billing integration, not credentials or event names from Paddle Classic.
Prepare separate sandbox and live credentials. Keep API keys and webhook secrets on the server.

Connect the gateway

Open the payment gateway settings in the admin and select Paddle.
Enter the API and client-side credentials requested by the current form, together with the webhook signing secret.
Select the sandbox environment for testing. Never mix a sandbox token with a live API key.
In Paddle, create the notification destination for your installation's Paddle webhook endpoint.

The endpoint used by this integration is https://your-store.example/api/payment/webhooks/paddle. Confirm the actual route for your installed release before configuring it.

Use current Billing events

Paddle Billing uses dotted event names. Payment completion is reported with transaction.completed; subscriptions use events such as subscription.created and subscription.updated. Select the events handled by your installed driver. Do not use an old Classic list such as payment_succeeded.

Verify before going live

Complete a sandbox checkout, check its order and transaction state, and confirm that the signed webhook is accepted. For recurring products, test creation, a renewal and cancellation. A duplicate notification must not create a second fulfilment or charge.

Gateway approval, supported products, currencies, taxes and payout terms come from Paddle. Check their current documentation: Paddle Billing webhooks.

Troubleshooting

For an authentication failure, check the environment and credentials. For a signature failure, check the destination secret and endpoint. For a pending order, inspect its payment and webhook status before retrying. Do not send a secret key in a support ticket.