Sell Through Paddle as Merchant of Record

Selling software and digital downloads to buyers in dozens of countries means sales tax, VAT and invoices that meet each country’s rules. Doing that yourself takes registrations and filings most small stores never get around to.

Paddle is a merchant of record: it sells to the buyer, works out the tax and remits it. The Paddle module connects Paddle Billing to Easy Digital Downloads. Buyers pay in Paddle’s overlay checkout, and orders, renewals, refunds and cancellations stay in step with EDD through signed webhooks.

Turn On the Gateway

1. Switch on the Paddle module under Stackless → Dashboard.
2. Add your keys under Stackless → Settings → Paddle and save.
3. Go to Downloads → Settings → Payments and switch on Paddle (Stackless) under Active Gateways. Save.

Paddle stays off the checkout until the current mode has both an API key and a client-side token.

Add Your API Keys

In Paddle → Developer tools → Authentication, create an API key with these permissions, then create a client-side token on the same screen:

transaction.read, transaction.write, subscription.read, subscription.write, adjustment.read, adjustment.write

Then fill in:

• Sandbox: on by default. Uses the Paddle sandbox, so no real money moves. Sandbox keys come from sandbox-vendors.paddle.com with the same permissions. This switch is separate from EDD’s Enable Test Mode.
• Live API key, Live client-side token and Live webhook secret key
• Sandbox API key, Sandbox client-side token and Sandbox webhook secret key

When you save, Stackless checks that each key sits in the right field. A sandbox key in a live field, or a live token in a sandbox field, shows an error. A changed API key is tested with Paddle. With the gateway switched on, a missing key, token or webhook secret for the selected mode shows an error.

You can also set these as wp-config.php constants, which win over saved settings:

STACKLESS_EDD_PADDLE_LIVE_API_KEY
STACKLESS_EDD_PADDLE_LIVE_CLIENT_TOKEN
STACKLESS_EDD_PADDLE_LIVE_WEBHOOK_SECRET
STACKLESS_EDD_PADDLE_SANDBOX_API_KEY
STACKLESS_EDD_PADDLE_SANDBOX_CLIENT_TOKEN
STACKLESS_EDD_PADDLE_SANDBOX_WEBHOOK_SECRET

Approve Your Site and Connect the Webhook

Paddle only opens its checkout on approved domains. The Checkout page and webhook section of the settings lists the steps with your own domain and URLs filled in:

1. In Paddle → Settings → Website approval, add your domain and wait for approval.
2. In Paddle → Checkout → Checkout configuration, set the default payment link to your store’s home page. Stackless sends its own checkout page with every payment, so Paddle only needs an approved default.
3. In Paddle → Developer tools → Notifications, add a destination with https://yoursite.com/wp-json/stackless-edd/v1/paddle/webhook.
4. Select the events below, then copy the secret key into the matching webhook secret key field.

transaction.paid
transaction.completed
transaction.payment_failed
subscription.created
subscription.activated
subscription.trialing
subscription.updated
subscription.past_due
subscription.paused
subscription.resumed
subscription.canceled
adjustment.created
adjustment.updated

Do this once for live and once in the sandbox. Webhooks confirm payments when a buyer closes the tab before coming back, record renewals, and bring refunds and cancellations made in Paddle into EDD. Each delivery is signature-checked and applied once.

Set How Tax Works

• Prices and tax: Use my Paddle account setting (default), Add tax on top of my prices or My prices already include tax.
• Tax category: Standard digital goods (approved for every account), which is the default, Digital goods, Ebooks, Implementation services, Professional services, Software as a service, Software programming services, Training services or Website hosting. Any category other than Standard must be approved for your Paddle account first, or checkouts fail.

Paddle calculates sales tax and VAT itself. Turn off EDD taxes for downloads you sell through Paddle, or buyers get taxed twice. The order note shows what Paddle charged including tax.

What Buyers See

At checkout, Paddle shows with the title “Card, PayPal, Apple Pay or Google Pay (Paddle)” and a description saying the buyer finishes paying in Paddle’s secure checkout. Both are editable. In sandbox mode, checkout adds “Sandbox mode: no real payment will be taken.”

• Purchasing opens Paddle’s overlay right over the EDD checkout, with the buyer’s email filled in.
• Without JavaScript, and for order payment links, the buyer goes to a Stackless pay page on your site that opens the same overlay.
• After paying, the buyer lands on the EDD receipt for the order.
• If Paddle reports a payment in a different currency or for a different amount, the order goes on hold with a note to check it.

Nothing has to exist in your Paddle catalog. Each transaction carries its own prices from EDD, so there’s nothing to set on your downloads.

Subscriptions on Paddle

Paddle runs the renewal schedule for subscriptions it bills:

• One-time downloads and a signup fee can share the checkout with a subscription. Paddle charges them once with the first payment.
• Free trials work when the first payment is zero. A signup fee or other items can’t be charged during a free trial.
• Each renewal Paddle charges becomes a paid EDD renewal order. The next payment date follows Paddle’s.
• Paddle’s trialing shows as Trial, past due and paused as On hold, canceled as Cancelled, and a cancellation scheduled for the end of the period as Pending cancellation.
• After the last payment of a fixed-length plan, Stackless tells Paddle to stop at the end of the period.

Cancelling from the EDD admin or the customer account cancels at Paddle too, at the end of the paid period or straight away. Paddle can’t schedule a cancellation for a paused or past-due subscription, so those end straight away. If Paddle doesn’t confirm, the cancellation is refused.

Customers get an Update payment method button on Paddle subscriptions in their subscription portal. It opens Paddle’s own checkout for replacing the card.

A subscription with the Renewal mode “Manual only (customer pays each renewal invoice)” isn’t billed by Paddle. Its first order and each renewal are paid through Paddle as one-time payments.

Refunds and Chargebacks

• The EDD refund form gets a Refund transaction in Paddle box. It’s unticked by default, so tick it to send the refund to Paddle. Paddle is called before EDD records the refund, so a refund Paddle refuses is never recorded.
• A partial refund is spread over the transaction’s line items. When Paddle added tax on top, the refund is scaled up to include it.
• Paddle may hold a refund for approval. The order note says so, and a refund Paddle later rejects is flagged on the order.
• Refunds made in the Paddle dashboard are recorded on the order through the webhook.
• Chargebacks reported by Paddle add an order note to review them in Paddle.

More Than One Paddle Account

Paddle can be duplicated for a second account, each copy with its own keys, orders and webhook URL ending in /webhook/copy2 and so on. See Duplicate a Payment Gateway.

Limits

• Paddle bills one subscription schedule per checkout. Subscriptions with different billing schedules have to be bought separately, and Paddle isn’t offered for carts it can’t take.
• Paddle charges at least one full billing cycle on the first payment, so a subscription with a first-payment discount can’t use Paddle.
• Paddle is offered for 33 currencies: USD, EUR, GBP, JPY, AUD, CAD, CHF, HKD, SGD, SEK, ARS, BRL, CLP, CNY, COP, CZK, DKK, HUF, ILS, INR, KRW, MXN, NOK, NZD, PEN, PLN, RUB, THB, TRY, TWD, UAH, VND and ZAR.
• Paddle doesn’t save cards in EDD. Customers can’t renew early, resume a pending cancellation or switch renewal mode from their account, and you can’t change the next payment date.
• Turn on Debug log to write Paddle activity to Downloads → Tools → Debug Log, tagged stackless-edd-paddle_gateway, while EDD debug mode is on. Keys are never logged.