Paddle Pay setup guide

Everything from creating your Paddle account to taking your first live payment. Follow the numbered steps in order.

In short

Connect your Paddle sandbox and live API keys in the Paddle Pay dashboard (Connections).
Connect your checkout subdomain (Checkout domain) and set the default payment link and website approval in Paddle.
In your CRM, set Paddle Pay as the default payment provider (Payments → Integrations).
Sell as usual: create products in your CRM and add them to an order form, a form’s product/payment element, your store, an invoice or a payment link. Paddle’s checkout opens automatically.
Manage everything (payments, refunds, invoices, subscriptions, customers, discount codes, exports) from the Paddle Pay dashboard.

How it works

Paddle Pay connects your CRM to your own Paddle Billing account. When a customer pays in a funnel, website, store, invoice or payment link:

Your CRM opens the Paddle Pay checkout, which loads Paddle’s secure card form and an order summary.
Paddle charges the customer as Merchant of Record: it calculates and collects sales tax or VAT, sends the receipt and handles the payment.
Paddle Pay confirms the payment and your CRM marks the order paid. Money is paid out to you by Paddle.

Each CRM account connects its own Paddle account. Paddle Pay never holds your money.

Before you start

A CRM account where you can install apps and manage payments.
A Paddle account. Sandbox, for testing, is instant. Live needs Paddle’s approval, which can take a few days.
Your own website and domain (for example yourbusiness.com) where you can add DNS records. Paddle only opens live checkout on a website it has approved for you.
Something Paddle allows you to sell. Paddle supports digital products, software, SaaS, online courses and similar. It does not support physical goods or most in-person services. Check Paddle’s Acceptable Use Policy before you start.

1. Create your Paddle accounts

Paddle has two separate environments, each with its own login, settings and API keys:

Sandbox at sandbox-vendors.paddle.com: test payments with test cards. No approval needed.
Live at vendors.paddle.com: real payments.

Live account onboarding

In your live Paddle account, finish every onboarding step Paddle shows you:

Business details: legal business name, address and what you sell. The legal name must match the name on your website’s terms.
Identity verification for the business owner.
Payout details: the bank account Paddle pays you into.
Website approval: covered in step 7.

Until Paddle finishes reviewing your live account, live checkouts fail with “Transaction checkout creation is blocked for this vendor”. That’s normal. Use sandbox in the meantime.

2. Install the app in your CRM

Open your CRM’s app marketplace, find Paddle Pay and click Install, or use this install link.
Choose the account (or accounts) to install it in and approve the permissions. The app needs to read your products and prices, and to manage payment integrations, orders and transactions.
You’ll see an “Installed” confirmation. Paddle Pay now appears under Payments → Integrations, and as a Paddle Pay item in the account menu that opens the dashboard.

3. Create Paddle API keys

Create one key in sandbox and another in live. Do the same steps in each:

In Paddle, go to Developer tools → Authentication, open API keys and click New API key.
Name it Paddle Pay and give it these permissions:

Permission	Why it’s needed
`customer.read, customer.write`	Finds or creates the Paddle customer for the buyer’s email.
`transaction.read, transaction.write`	Creates the transaction for each order and checks whether it was paid.
`adjustment.read, adjustment.write`	Sends full and partial refunds you issue in your CRM.
`subscription.read`	Reads subscriptions created from recurring products.
`subscription.write (optional)`	Cancel, pause and resume subscriptions from the dashboard.
`payment_method.read`	Lists a customer’s saved cards for your CRM.
`notification_setting.read, notification_setting.write`	Creates the webhook that tells the app when a payment completes.
`client_token.write`	Creates the client-side token that opens Paddle checkout.
`checkout_domain.read (optional)`	Shows your domain’s Paddle approval status in the dashboard.
`discount.read, discount.write (optional)`	Create and archive discount codes from the dashboard.
`report.read, report.write (optional)`	Export transactions to CSV from the dashboard.
`notification.read, notification.write (optional)`	Show webhook deliveries and resend failed ones.
`customer_portal_session.write (optional)`	Create customer portal links (customers update their card or cancel).

Save and copy the key straight away. Paddle only shows it once. Sandbox keys start with pdl_sdbx_, live keys with pdl_live_.
If you set an expiry date, note it: when the key expires, payments stop until you connect a new one.

Treat API keys like passwords. Paddle Pay stores them encrypted and never shows them again.

4. Connect Paddle

Open the Paddle Pay dashboard from your CRM (the Paddle Pay menu item, or Payments → Integrations → Paddle Pay).
Go to Connections. Paste the sandbox key into Sandbox and click Connect. Then do the same with the live key in Live.

When you connect, Paddle Pay checks the key’s permissions and creates three things in your Paddle account automatically:

a client-side token that opens checkout;
a notification destination (webhook) named Paddle Pay … that reports completed payments, subscriptions and refunds;
the webhook’s signing secret, so the app can verify messages really come from Paddle.

Don’t delete or pause the “Paddle Pay” token or notification destination in Paddle. If you do, orders won’t be marked paid. Clicking Replace key recreates them.

5. Connect your checkout domain

Paddle only opens live checkout on a domain approved in your Paddle account, so checkout needs to run on a subdomain of your own website. Pick one that isn’t used for anything else, for example pay.yourbusiness.com.

In the dashboard, open Checkout domain.
Enter the subdomain, plus your main website address (any other page on the subdomain redirects there). Click Connect domain.
The dashboard shows a CNAME record, and sometimes a TXT record. Add them where your domain’s DNS is managed:
- Name / Host: some providers want the full name (pay.yourbusiness.com), others only the first part (pay). GoDaddy and Namecheap use the short form.
- Value / Points to: copy it exactly with the Copy button.
- Cloudflare: set the record to DNS only (grey cloud), not Proxied.
- TTL: leave the default.
Wait. The status changes from Waiting for DNS to Securing with HTTPS to Active, usually within minutes and occasionally up to an hour. You can click Check now at any time.

Once it’s Active, your CRM’s checkout loads from your subdomain automatically.

Only this subdomain needs Paddle approval. Your CRM’s own invoice, payment-link and form domains, and your funnel and website domains, don’t need approval: Paddle checkout runs inside the frame served from your checkout subdomain, and that’s the domain Paddle checks.

6. Set the default payment link

Paddle refuses to create checkouts until a default payment link is set. In both sandbox and live Paddle:

Go to Checkout → Checkout settings.
Set Default payment link to your checkout domain’s link, shown in the dashboard with a Copy button: https://pay.yourbusiness.com/checkout.
Save.

Paddle uses this link in emails it sends (for example to retry a failed payment), and Paddle Pay opens those links correctly. In sandbox you can use https://paddle-pay-connect.vercel.app/checkout until your own domain is ready, because sandbox accepts any domain.

7. Get your website approved

In live Paddle, open Website approval (under Checkout, or Settings in newer dashboards). Submit your checkout subdomain, for example pay.yourbusiness.com. Paddle approves each exact host, so submit the subdomain itself even if your main domain is already approved. Sandbox approves domains automatically.

What Paddle reviews

Paddle looks at your main website. Before you submit, make sure it has:

A clear description of what you sell, with prices visible.
Terms and conditions that name your legal business name, matching your Paddle account, and say that Paddle is the Merchant of Record. Paddle’s suggested wording: “Our order process is conducted by our online reseller Paddle.com. Paddle.com is the Merchant of Record for all our orders. Paddle provides all customer service inquiries and handles returns.”
A privacy policy.
A refund policy that’s easy to find. Many Paddle sellers offer at least 14 days.
Contact details: at least a support email.
A working site: no “coming soon” pages or placeholder text, and links to the terms, privacy and refund pages, usually in the footer.

Review usually takes a few days. The dashboard’s Checkout domain tab shows the status (Pending review, Approved, Rejected or Action required) if your API key has checkout_domain.read. If Paddle rejects it, its email says what to change. Fix that and resubmit.

8. Make Paddle Pay your payment provider

In your CRM, open Payments → Integrations.
Find Paddle Pay and click Set as default.
Your CRM has a test mode and a live mode for payments. Test mode uses your sandbox key; live mode uses your live key. Make sure the matching key is connected.

9. Test a payment

Switch your CRM’s payments to test mode.
Open one of your order forms, invoices or payment links and pay with a Paddle test card:
- Successful payment: 4242 4242 4242 4242
- 3D Secure challenge: 4000 0038 0000 0446
- Declined: 4000 0000 0000 0002
Use any future expiry date, CVC 100 and any name. Paddle’s developer docs list more test cards.
Check that the order shows as paid in your CRM and as Paid under Recent payments in the dashboard.
Test a refund from your CRM, and a recurring product if you sell subscriptions.

10. Go live

☐ Live Paddle onboarding complete (no “blocked for this vendor” error).
☐ Live API key connected in Connections.
☐ Checkout domain Active, and approved in live Paddle.
☐ Live default payment link set to your checkout domain.
☐ Paddle Pay set as default in Payments → Integrations.
☐ Your CRM’s payments switched to live mode.
☐ One small real purchase made, then refunded.

Selling: forms, funnels, store, invoices

Paddle Pay doesn’t add its own buttons. It powers the payment step of whatever you already sell with in your CRM. Every sale starts from a product:

Create the product in your CRM (Payments → Products): name, price and currency. For a subscription choose a recurring price (daily, weekly, monthly or yearly) and, optionally, trial days.
Add it where customers buy:
- Funnels and websites: on an order form step, add the product to the step’s products, and keep the order form element (with its payment section) on the page.
- Forms: add the product / payment element (the “sell product” element) to the form and pick the products it sells. When the form is submitted, the payment step opens Paddle checkout.
- Store: products added to your store use the store’s checkout, which uses Paddle Pay.
- Invoices and text-to-pay: create the invoice as usual. The customer’s “Pay” button opens Paddle checkout.
- Payment links: create a payment link for the product and share it.
Publish and make a test purchase in test mode (step 9).

The amount and currency always come from your CRM product. Paddle adds sales tax or VAT for the buyer’s location, and the order summary next to the card form shows it.

Managing payments in the app

You don’t need to open Paddle for day-to-day work. Every tab has a Live / Sandbox switch.

Transactions: Every payment, searchable by customer email, name or ID and filterable by status. Open one to see items, tax, Paddle’s fee and your earnings, download the invoice PDF, see past refunds, and issue a full or partial refund. Export CSV creates a spreadsheet of transactions for any date range.
Subscriptions: All subscriptions with their status and next payment date. Open one to cancel at period end, cancel now, undo a pending cancellation, pause or resume, or see its payments.
Customers: Search customers and see each one’s total paid, subscriptions and payments. Customer portal link copies a secure link you can send so the customer can update their card or manage their subscription.
Discounts: Create discount codes (percentage or fixed amount, usage limit, expiry, optionally applied to renewals), archive or restore them, and switch the discount code field in checkout on or off.
Connections → Webhook deliveries: See the messages Paddle sent to the app and send failed ones again. Useful if an order wasn’t marked paid.

Some things can only be done in Paddle’s dashboard, because Paddle has no API for them: the default payment link and checkout branding, website approval, business and identity verification, payout bank details, and turning on payment methods such as PayPal or Apple Pay.

The management features use the optional API key permissions marked in step 3. If one is missing, the dashboard tells you which permission to add.

Where payments work

Works	Doesn’t work
Funnel and website order forms, including order bumps Store checkout Invoices, including text-to-pay links Payment links One-time and recurring products Full and partial refunds from the CRM	One-click upsells after checkout Charging a saved card from a contact’s record Saving a card without a payment Physical products, and services Paddle doesn’t allow The unsupported payment types all charge a card without the customer present. Paddle only allows that inside subscriptions.

Works

Doesn’t work

Funnel and website order forms, including order bumps
Store checkout
Invoices, including text-to-pay links
Payment links
One-time and recurring products
Full and partial refunds from the CRM

One-click upsells after checkout
Charging a saved card from a contact’s record
Saving a card without a payment
Physical products, and services Paddle doesn’t allow

The unsupported payment types all charge a card without the customer present. Paddle only allows that inside subscriptions.

Subscriptions

When a customer buys a recurring product, Paddle Pay creates a Paddle subscription with the same interval (daily, weekly, monthly or yearly) and any free trial days.
Paddle charges each renewal automatically, and each renewal is reported back to your CRM.
Paddle emails customers a link to manage their subscription: update their card or cancel. You can cancel, pause or resume subscriptions, or send a customer portal link, from Subscriptions in the Paddle Pay dashboard.

Refunds

Issue refunds from the order or transaction in your CRM, or from Transactions in the Paddle Pay dashboard, either full or partial. Paddle Pay sends them to Paddle.
Paddle may hold a refund for approval first. It then shows as pending until Paddle approves it. Sandbox refunds are approved automatically about every 10 minutes.
The money goes back to the customer’s original payment method, usually within 5 to 10 business days.

Tax, receipts and payouts

Paddle is the Merchant of Record. It calculates, collects and pays sales tax and VAT for each buyer’s country, so you don’t have to register for tax in each country.
The checkout shows tax in the order summary once Paddle knows the buyer’s location. Whether your prices include or exclude tax is set in Paddle.
Paddle emails buyers their receipt or invoice, and statements show Paddle as the seller.
Paddle pays your earnings, minus its fees, to the payout account you set up. See your balance and payouts in Paddle.

Checkout branding

The card form’s colours, logo and style come from your Paddle account. Set them under Checkout → Checkout settings, in both sandbox and live. The business name shown (“Provided by …”) is your Paddle business name. The order summary next to the form comes from your CRM product names and prices.

The dashboard

Overview: Live revenue and sandbox volume for the last 30 days, subscriptions started, connection status, a setup checklist and your latest payments.
Payment statuses: Paid: completed. Awaiting payment: checkout was opened but not paid. These are abandoned or still-open checkouts, and nobody was charged. Past due: a subscription renewal failed. Canceled: the transaction was cancelled.
Transactions, Subscriptions, Customers, Discounts: See Managing payments in the app.
Connections: Connect, replace or disconnect your sandbox and live Paddle keys, and see webhook deliveries.
Checkout domain: Connect your own checkout subdomain, see its DNS records and its Paddle approval status.
Setup guide: A short version of this guide.

Troubleshooting

Find the message you see:

Cannot create a transaction or open a checkout as no default payment link has been set for this account: Paddle needs a default payment link before it opens any checkout. Set it in Paddle under Checkout → Checkout settings (step 6). Do this separately in sandbox and live.
Transaction checkout creation is blocked for this vendor: Your live Paddle account isn’t cleared to sell yet. Finish Paddle’s onboarding (business details, identity verification, payout details, website approval). If everything shows complete, contact Paddle support with this exact message. Only Paddle can lift it.
Paddle checkout did not load: Usually the domain checkout runs on isn’t approved in your Paddle account, or there’s no default payment link. Check steps 5 to 7.
Payment failed / an error code in brackets: The text before the brackets is Paddle’s own reason, and the code identifies it. Card declines come from the bank: ask the buyer to try another card. For anything else, send us the message and code.
This Paddle API key is missing a permission (…): Edit the key in Paddle → Developer tools → Authentication, tick the permission named in the message (see step 3), save, and connect again.
Paddle rejected this API key: The key was copied incompletely, has expired, or was revoked. Create a new key and connect again.
This field needs a sandbox/live key: Sandbox keys start with pdl_sdbx_ and go in the Sandbox card; live keys start with pdl_live_ and go in the Live card.
Open this page from inside your CRM: The dashboard only works inside your CRM, because that’s how it knows which account you’re in. Open Payments → Integrations → Paddle Pay, or the Paddle Pay item in the account menu. If it still appears inside the CRM, reload the page.
Paddle Pay is not installed for this account: Install the app again from your CRM’s app marketplace and pick this account.
Waiting for payment details from the checkout page: The CRM didn’t send the order to the checkout. Reload the page and check that Paddle Pay is set as the default provider (step 8) in the same mode (test or live) you’re paying in.
Paddle is not connected for this account: No Paddle key is connected for the mode the CRM is in. Connect a sandbox key for test mode and a live key for live mode.
Checkout domain stuck on “Waiting for DNS”: Check that the CNAME record has exactly the name and value shown, with no extra dots. On Cloudflare, set it to DNS only (grey cloud). DNS can take up to an hour; the page re-checks every 20 seconds.
Checkout domain stuck on “Securing with HTTPS”: DNS is correct and the security certificate is being issued. This normally takes a few minutes. If it takes more than an hour, remove the domain and add it again.
That domain is already connected to another website or hosting account: Remove the subdomain from the other service first, or use a different subdomain such as checkout.yourbusiness.com.
Payment went through but the order isn’t marked paid: The app confirms payments through a webhook it created in Paddle (Developer tools → Notifications, named “Paddle Pay …”). Don’t delete or pause it. If it was removed, click Replace key in Connections and paste your key again, which recreates it.
Refund shows “pending approval”: Paddle reviews some refunds before approving them. In sandbox, refunds are approved automatically about every 10 minutes.

Disconnect or uninstall

Disconnect (in Connections) stops payments in that mode. It revokes the token and deletes the webhook that Paddle Pay created in your Paddle account.
Remove domain sends checkout back to the app’s own domain. You can then delete the DNS record.
Uninstalling the app from your CRM does all of the above for that account and deletes your stored keys. Your Paddle account, customers, transactions and subscriptions stay in Paddle.

Security and data

Card details are entered directly into Paddle’s secure form. Paddle Pay never sees or stores card numbers.
API keys and webhook secrets are encrypted at rest (AES-256). Every webhook from Paddle is checked against its signature.
See the Privacy Policy for exactly what is stored and for how long.

FAQ

Can I use one Paddle account for several CRM accounts?: Yes. Connect the same Paddle keys in each account. Each account gets its own token and webhook in Paddle. Each account’s checkout domain must also be approved in that Paddle account.
Do I need a checkout domain for sandbox?: No. Sandbox works on the app’s own domain. You need your own domain for live.
Which currencies are supported?: Any currency Paddle supports for your account. The checkout charges the currency set on the CRM product.
Can customers use PayPal, Apple Pay or Google Pay?: Yes, if they’re turned on in your Paddle account. Apple Pay also requires Paddle to verify your checkout domain for Apple Pay.
What does it cost?: A one-time payment of $997 for lifetime access, with a 14-day money-back guarantee. See pricing. Paddle charges its own fees per transaction, separately.

Support

Still stuck? Contact us with the exact error message and, if you can, a screenshot: IR Solutions · Muzaffargarh, Punjab, Pakistan.