Paddle
Overview¶
Paddle integration is another option offered by Nadles for payment collection.
Paddle is a payment solution provider serving as a Merchant of Record.
Using a merchant of record allows you to collect payments internationally without the need to care about different taxation rules between countries.
When Nadles's Paddle integration is used, Paddle handles recurring payments and invoices. However, Paddle doesn't offer Pay-per-use functionality out of the box, meaning, you can't charge your customers for what they actually use.
But with Nadles you can.
Nadles adds missing usage-based billing functionality to Paddle: it records usage data for each subscription and creates the corresponding charges in Paddle, so that customers are correctly billed for the actual usage at the end of each billing period.
Info
In contrast to API marketplaces, Nadles doesn't act as a middleman in the payment process.
All payments are made directly to your Paddle account.
Prerequisites¶
- Active Paddle account
- SaaS taxable category approved for your account by Paddle
- Your own domain name approved by Paddle
- Paddle overlay checkout page set up on your own domain
Subscription flow with Paddle¶
sequenceDiagram
autonumber
User->>Nadles: Click "Subscribe"
Nadles-->>User: Inactive subscription created
User->>Nadles: Click "Activate subscription"
Nadles->>Paddle: Sync user data
Nadles->>Paddle: Create a product copy
Nadles->>Paddle: Create a checkout transaction
Nadles-->>User: Redirect to Paddle checkout page on yourdomain.com
User->>yourdomain.com/paddle-checkout: Enter payment details and pay
Paddle-->>Nadles: Notify about successful payment
yourdomain.com/paddle-checkout-->>User: Redirect to Nadles success URL
Nadles-->>User: Subscription activated
Nadles-->>User: Access to the API granted
- The customer clicks "Subscribe" on the Nadles checkout page.
- Nadles creates a subscription in an "incomplete" state. The customer has to make a payment in order to activate the subscription.
- After clicking the "Activate subscription" button on the subscription page, the customer is transferred to the Paddle checkout page on your domain, to complete the payment.
- Once the payment succeeds, Paddle redirects the customer back to Nadles.
- Nadles activates the subscription for the customer, issues a new API key and enables access to your APIs.
Setting up Paddle account¶
For Nadles to successfully manage your Paddle products and subscriptions, the following data is required:
- Your Paddle seller ID
- API key
- Webhook secret key
Nadles stores this information in encrypted form, you won't be able to see it again once it's saved.
Follow the steps below to obtain the necessary credentials.
API key and seller ID¶
- On Paddle, navigate to Developer tools → Authentication.
- Copy your seller ID into the "Your Paddle vendor ID" field on Nadles.
- Click Generate API Key.
- Enter "Nadles" as key name.
- Copy the generated key to the setup form on Nadles.
Webhook¶
- On Paddle, navigate to Developer tools → Notifications.
- Click New destination.
- Enter "Nadles" as description.
- Select Notification type "Webhook".
- Copy your Paddle webhook URL from Nadles to the "URL" field.
- Check the Select all event checkbox.
- Click Save destination.
- After that, click Edit destination and copy the webhook signing secret to the Nadles setup form.
- Save the Paddle integration form on Nadles.
Note
We recommend adding another notification destination for your e-mail, so you're always aware of the events occurring on your account.
Setting up checkout page¶
General¶
In order to accept payments via Paddle, you need to build an overlay checkout page that accepts Paddle transaction ID and host it on your domain.
The overlay checkout page can be as simple as a single HTML page with a bit of JS code.
Let's say you own the domain name myfirstapi.example
and plan to host the Paddle checkout page on https://myfirstapi.example/paddle-checkout
Follow the steps below to get your Paddle checkout up and running.
Domain verification¶
First, get myfirstapi.example
approved by Paddle. What is domain verification?
Default payment link¶
Second, set up your default payment link on Paddle to:
https://myfirstapi.example/paddle-checkout
Nadles will redirect your customers to this page to make a payment.
Two query string parameters will be added to the URL:
_ptxn
— a checkout transaction ID, added by Paddle. Learn more._px_success_url
— success URL, added by Nadles. Paddle will redirect the customer to this URL after the payment succeeds.
Paddle checkout page¶
Third, build the checkout page and host it on your website.
Feel free to use the following template and customize as needed:
<!DOCTYPE html>
<html>
<body>
<script src="https://code.jquery.com/jquery-3.7.1.min.js" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo=" crossorigin="anonymous"></script>
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script type="text/javascript">
Paddle.Environment.set("sandbox"); // replace with "production" before going live
Paddle.Setup({
token: '7d279f61a3499fed520f7cd8c08' // replace with your client-side token
});
$(function() {
var urlParams = new URLSearchParams(window.location.search);
Paddle.Checkout.open({
transactionId: urlParams.get('_ptxn'),
settings: {
theme: "light",
locale: "en",
successUrl: urlParams.get('_px_success_url')
}
});
});
</script>
</body>
</html>
Now deploy the page on https://myfirstapi.example/paddle-checkout
and you're good to go.
That's it. Paddle integration is set up and ready.
Notes and limitations¶
- All prices in a product must have the same billing period.
- Unlike Stripe, cancelation is not immediate with Paddle. Instead, subscriptions are scheduled to be canceled at the end of a billing period.
- Maximum number of quota units is 999999999. That's Paddle's limitation.