Skip to content

Paddle

Overview

Paddle integration is another option offered by Project X 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 Project X'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 Project X you can.

Project X 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, Project X 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->>Project X: Click "Subscribe"
  Project X-->>User: Inactive subscription created
  User->>Project X: Click "Activate subscription"
  Project X->>Paddle: Sync user data
  Project X->>Paddle: Create a product copy
  Project X->>Paddle: Create a checkout transaction
  Project X-->>User: Redirect to Paddle checkout page on yourdomain.com
  User->>yourdomain.com/paddle-checkout: Enter payment details and pay
  Paddle-->>Project X: Notify about successful payment
  yourdomain.com/paddle-checkout-->>User: Redirect to Project X success URL
  Project X-->>User: Subscription activated
  Project X-->>User: Access to the API granted
  1. The customer clicks "Subscribe" on the Project X checkout page.
  2. Project X 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 Project X.
  5. Project X activates the subscription for the customer, issues a new API key and enables access to your APIs.

Setting up Paddle account

For Project X to successfully manage your Paddle products and subscriptions, the following data is required:

  • Your Paddle seller ID
  • API key
  • Webhook secret key

Project X 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 Project X.
  3. Click Generate API Key.
  4. Enter "Project X" as key name.
  5. Copy the generated key to the setup form on Project X.

Webhook

  1. On Paddle, navigate to Developer tools → Notifications.
  2. Click New destination.
  3. Enter "Project X" as description.
  4. Select Notification type "Webhook".
  5. Copy your Paddle webhook URL from Project X 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 Project X setup form.
  9. Save the Paddle integration form on Project X.

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

Project X 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 Project X. 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.