Beta. The Paddle connector is built and tested against Paddle Billing's documented, signed webhook events. It has not yet run against a live Paddle account in production. Try it in Paddle's sandbox first.
Paddle
Connect Paddle as your merchant of record so global tax is handled for you while its transactions reach your revenue and its subscriptions grant access.
Paddle acts as the merchant of record: it is the legal seller of your product, then handles global sales tax, VAT, invoicing, and chargebacks on your behalf. Connect Paddle to CashSDK and each completed transaction lands in the same revenue analytics as your store purchases, while each subscription's status grants and ends the entitlements your app checks, the way an App Store subscription does.
Because Paddle is the merchant of record, you never register for tax in each market: Paddle collects and remits it. CashSDK records each transaction's total as Paddle reports it. Reach for Paddle when you sell cross-border on the web and want compliance off your plate.
How it works#
1
Connect your Paddle account
Connect Paddle from your app's Marketplace page with a Paddle Billing API key and the notification secret key.
2
Map prices to entitlements
Each Paddle price ID (pri_…) matches a CashSDK product and the
entitlement it unlocks. A transaction with several items is recorded under
its first item's price.
3
Receive signed webhooks
Completed transactions become revenue. A refund counts once Paddle approves it, and subscription events grant and end access.
Connect Paddle#
1
Create an API key
In Paddle, open Developer Tools → Authentication and create an API key. Copy it now. Paddle shows the full key only once.
2
Add it to CashSDK
In the dashboard, open your app's Marketplace page, choose Paddle and select Connect. Pick Sandbox or Production to match the Paddle environment and paste the key. Leave the signing secret empty for now. It is stored encrypted at rest.
3
Register the webhook
Copy the connection's webhook URL from the Connected list and add it in
Paddle under Developer Tools → Notifications as a new destination.
Subscribe to transaction.completed, adjustment.created,
adjustment.updated and the subscription events: subscription.created,
subscription.activated, subscription.updated, subscription.canceled,
subscription.paused, subscription.resumed, subscription.past_due and
subscription.trialing. Without adjustment.updated, a refund that waits for
Paddle's approval never comes off your revenue.
4
Activate
Copy the destination's secret key. Back in CashSDK, select Reconnect, enter the API key and that secret, then select Activate. A connection without a signing secret cannot be activated.
Map your catalog#
Payments for prices your app does not sell are skipped, so for each Paddle price
create a product in CashSDK whose identifier is the price
ID and attach the entitlement it unlocks. To point a price
at an existing product instead, map it with map_marketplace_catalog
(prompt setup).
- A one-time purchase unlocks a non-consumable product for good.
- A subscription grants access while Paddle reports it
active,trialingorpast_due. A cancellation scheduled for the end of the billing period keeps access until then. - A refund counts once Paddle approves it: it comes off your revenue by its amount, and a refund of the whole transaction also ends the access that transaction gave. A pending or rejected refund changes nothing.
Who gets access#
Set cashsdk_user_id in the subscription's custom_data, for example by passing
it in customData when you open the checkout. CashSDK reads it from the
subscription events and remembers it for that subscription. Without it, and for
one-time purchases, the Paddle customer ID (ctm_…) stands in for the user. Link
it to the right user with the link_marketplace_user tool on the
MCP server.
Test and go live#
1
Test in the sandbox
With a Sandbox connection and a Paddle Sandbox API key, complete a checkout with a test card. Confirm the transaction appears under Transactions and the entitlement is granted to your test user.
2
Switch to production
Add a Production connection with your production API key, its own notification destination and secret key. Your CashSDK publishable key does not change.