How do I setup Paddle Billing as a payment gateway

What is Paddle Billing in HostShop? 

Paddle Billing is a HostShop payment gateway that takes card payments and renews hosting packages automatically through Paddle subscriptions. Paddle acts as the merchant of record, so Paddle calculates, collects and pays the sales tax or VAT on each sale for you. 

Who it suits: Resellers who sell internationally or across US states and don't want to register for and file sales tax themselves. 

Paddle Billing vs Paddle Classic: Paddle Billing is Paddle's current platform. Paddle Classic is closed to new Paddle merchants, so HostShop no longer offers it for new gateways. Existing Paddle Classic gateways keep working. If both are enabled, checkout only offers Paddle Billing. 

Prices include tax: with HostShop's own tax turned off, the price you set in HostShop is the total your customer pays. Paddle works out the tax inside that amount, so your payout is the price minus tax and Paddle's fees. 

Use it on its own: turn off HostShop's tax settings and use Paddle Billing as your only payment gateway. See Should I turn off HostShop's tax settings when using Paddle Billing? below. 

What do I need before setting up Paddle Billing? 

You need an approved Paddle Billing account and four settings in your Paddle dashboard. Paddle checks each business before it enables live payments, so apply at paddle.com early. 

Approve your website: in Paddle, go to Checkout › Website approval and add the domain your HostShop storefront uses. Paddle won't open checkout on an unapproved domain. 

Set a default payment link: go to Checkout › Checkout settings and enter your storefront address. Paddle won't create payments until this is set. 

Create an API key: go to Developer Tools › Authentication and create a key with read and write permission for transactions, customers, subscriptions, adjustments and notification settings, and read permission for events. Live keys start pdl_live_apikey_. 

Create a client-side token: on the same page. Live tokens start live_. This token is safe to use in the browser. 

Also check that the currencies you sell in are enabled in your Paddle account. Keep your API key private, as anyone with it can act on your Paddle account. 

How do I set up Paddle Billing in HostShop? 

Add Paddle Billing from the Payment Gateways page in My20i, and HostShop connects the Paddle webhook for you. 

• Go to HostShop › Payment Gateways. If you already have a gateway, click Add Payment Gateway at the top right. 
• Choose Paddle Billing and set Environment to Live. 
• Enter your API Key and Client-side Token. 
• Set a Checkout Label (the name customers see at checkout) and tick the Currencies to offer through Paddle. 
• Click Add Payment Gateway, then turn off HostShop's own tax in Tax Settings (see below). 

HostShop checks your keys with Paddle and creates a webhook in your Paddle account. The webhook is how Paddle tells HostShop about renewals, failed payments and cancellations. The gateway card shows Webhook configured when it's working. 

If the card shows "Webhook not configured": your API key is usually missing the notification settings permission. Add it in Paddle, then click Try again. Alternatively, create a notification destination in Paddle yourself for https://<your shop domain>/a/paymentGatewayEvents/paddlebilling, subscribe it to transaction, subscription and adjustment events, and paste its secret key into Webhook Secret Key. Without a webhook, customers can still pay, but nothing renews automatically. 

Should I turn off HostShop's tax settings when using Paddle Billing? 

Yes. Turn off HostShop's own tax and use Paddle Billing as your only payment gateway, because Paddle already calculates and pays the tax on every sale. 

Go to HostShop › Tax Settings. 

• Turn off VAT, US sales tax (including any nexus states) and any custom tax rates. 
• Disable your other payment gateways, so all customers pay through Paddle Billing. 

Why this matters: HostShop adds its tax to the basket before the customer chooses how to pay, so it applies to Paddle orders too. If it's left on: 

Customers paying with Paddle are charged HostShop's tax on top of your price, and Paddle accounts for its own tax inside that total. 

The tax shown on the HostShop basket and invoice can differ from the tax on Paddle's checkout and receipt, even though the total charged is the same. 

Paddle pays only its own tax figure. Don't file tax from your HostShop records for Paddle orders, as Paddle has already paid it. 

Using another gateway alongside Paddle Billing: HostShop's tax settings apply to every order, whichever gateway the customer uses. You can't charge HostShop tax on other gateways' orders without it also applying to Paddle orders, so we recommend Paddle Billing as your only gateway. 

How do I test Paddle Billing without taking real payments? 

Use a sandbox gateway with your Paddle sandbox account, then turn on Sandbox Mode while you test. 

• Create a Paddle sandbox account at sandbox-vendors.paddle.com. Set a default payment link there; sandbox accounts don't need website approval. 
• In HostShop, add Paddle Billing with Environment set to Sandbox, using the sandbox API key (starts pdl_sdbx_apikey_) and client-side token (starts test_). Sandbox gateways show a Sandbox label. 
• At the bottom of the Payment Gateways page, turn on Sandbox Mode. 
• Place a test order and pay with Paddle's test card 4242 4242 4242 4242, any future expiry date and any CVC. 
• Turn Sandbox Mode off when you've finished. 

Sandbox Mode applies to your whole shop. While it's on, checkout only offers your sandbox gateways, customers can't make real payments, and test orders don't set up services or create real invoices. You can have one live and one sandbox gateway of each type. 

What do customers see when they pay with Paddle Billing? 

Customers choose Paddle at checkout and pay in Paddle's secure checkout, which opens over your storefront. They can use any payment method you've enabled in your Paddle account. 

• The option is shown with your Checkout Label, and only for the currencies you ticked. 
• Customers can also pay an existing invoice with Paddle from their invoice page. 
• HostShop marks the invoice paid once Paddle confirms the payment. Occasionally, an order shows as pending for a short time until that confirmation arrives. 
• Paddle emails the customer a receipt with a PDF invoice for every payment. 

How do Paddle Billing subscriptions and renewals work? 

When a customer buys a hosting package with Paddle Billing, Paddle sets up a subscription and charges their card automatically at each renewal. HostShop doesn't charge Paddle Billing customers itself. 

Which purchases become subscriptions? 

Hosting packages with a renewal period become subscriptions, as long as the webhook is configured. Domains and one-off items are charged once. An order that mixes renewal periods, or whose first period is discounted, is charged once and then renews by invoice. 

What happens at each renewal? 

• Before expiry, HostShop raises the renewal invoice and updates the Paddle subscription to that invoice's amount and the contract's expiry date. Price changes and add-ons therefore carry over to Paddle. 
• On the expiry date, Paddle charges the customer's card. 
• HostShop marks the invoice paid, extends the contract and emails the customer a renewal confirmation. 

Turn on Generate invoice in your Renewal Sequence (Reseller › HostShop › Renewal Sequence) for Paddle Billing customers. Without it, price changes don't reach Paddle, and customers can get a payment failure email on the expiry date before Paddle has charged them. 

Which emails do customers receive? 

Customers receive emails from both HostShop and Paddle: 

HostShop's renewal invoice emails ask customers to pay, but Paddle Billing customers are charged automatically. Consider editing your renewal email templates to say so. A customer who pays the invoice by hand is still charged by Paddle and gets an extra renewal period. 

What happens if a renewal payment fails? 

Paddle retries the card and emails the customer to update their payment details, and you receive a payment failed email. If the invoice is still unpaid after expiry, your Renewal Sequence's after-expiry steps apply, such as overdue emails, lockout or cancellation. If Paddle collects the payment later, the invoice is paid and the service is renewed and restored. 

How do customers update their card or cancel? 

Customers click Manage payment next to the service on their Renewals page. This opens Paddle's customer portal, where they can update their card or cancel the subscription. 

How do I cancel or change a Paddle Billing subscription? 

• Cancelling the contract in HostShop cancels the Paddle subscription, so Paddle stops charging. 
• Changing the customer's renewal payment method in HostShop also cancels the Paddle subscription. 
• Cancelling in Paddle (dashboard or customer portal) switches the contract to normal invoice renewal. Paddle usually cancels at the end of the billing period, and HostShop updates when the subscription actually ends. 

How do I see which contracts renew through Paddle? 

On a customer's Access & Contracts page, these contracts show Managed by Paddle Billing under the expiry date. Their expiry date can't be edited, because Paddle controls when they renew. The contract's Renewal Log shows the renewal invoice, the Paddle update and each successful renewal. 

How do refunds, tax and payouts work with Paddle Billing? 

Paddle handles the money side: refunds are issued in Paddle, and Paddle files the tax and pays you out. 

• Refunds: issue refunds from your Paddle dashboard. A refund recorded on an invoice in HostShop only adjusts the invoice; it doesn't send money back to the customer. Paddle reviews refunds before making them, so they can take a short time to complete. 
• Abuse checks: if an order fails HostShop's abuse checks after payment, HostShop refunds it in Paddle automatically and cancels any subscription it created. 
• Tax: Paddle calculates, collects and pays sales tax and VAT on every sale, and issues the customer's invoice. Tax reports come from your Paddle dashboard. Keep HostShop's own tax settings turned off, so tax isn't charged twice. 
• Payouts and fees: Paddle pays out to you on its own schedule, after its fees. Check Paddle's pricing for the current rates. 

How do I move from Paddle Classic to Paddle Billing? 

You use the same Paddle account, and your customers don't need to do anything. 

• In your Paddle dashboard, switch your account to Paddle Billing. 
• Create an API key and client-side token as described above. 
• Add a Paddle Billing gateway in HostShop. While both are enabled, customers only see Paddle Billing at checkout. 
• Turn off HostShop's own tax settings, test with a small order, then disable Paddle Classic in HostShop. 

HostShop never set up Paddle Classic subscriptions, so there is nothing to migrate. Existing contracts switch to automatic renewal the next time the customer pays through Paddle Billing. Once deleted, a Paddle Classic gateway can't be added again. 

What do I need to do if I change my shop's domain? 

After changing your domain under Your Brand, update Paddle and re-save the gateway, or Paddle checkout and renewals stop working. 

• In Paddle, approve the new domain under Checkout › Website approval and update your default payment link. 
• In HostShop, open the Payment Gateways page. The Paddle Billing card usually warns that your shop has moved. 
• Click Update webhook, or save the gateway if there's no warning, so Paddle sends renewals and cancellations to the new domain. 

Troubleshooting Paddle Billing

Most Paddle Billing problems come from a Paddle account setting or the webhook.