Skip to content

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

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
  1. The customer clicks "Subscribe" on the Nadles checkout page.
  2. Nadles creates a subscription in an "incomplete" state. The customer has to make a payment in order to activate the subscription.
  3. 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.
  4. Once the payment succeeds, Paddle redirects the customer back to Nadles.
  5. 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

  1. On Paddle, navigate to Developer tools → Authentication.
  2. Copy your seller ID into the "Your Paddle vendor ID" field on Nadles.
  3. Click Generate API Key.
  4. Enter "Nadles" as key name.
  5. Copy the generated key to the setup form on Nadles.

Webhook

  1. On Paddle, navigate to Developer tools → Notifications.
  2. Click New destination.
  3. Enter "Nadles" as description.
  4. Select Notification type "Webhook".
  5. Copy your Paddle webhook URL from Nadles to the "URL" field.
  6. Check the Select all event checkbox.
  7. Click Save destination.
  8. After that, click Edit destination and copy the webhook signing secret to the Nadles setup form.
  9. 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?

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:

  1. _ptxn — a checkout transaction ID, added by Paddle. Learn more.
  2. _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.