Paddle

Pace integrates seemlessly with Paddle for handling subscriptions (subscribe, cancel, downgrade, upgrade, change payment method, etc.).

Create Paddle account

To integrate your application with Paddle, you must have an active Paddle account or sign up for one if you don't already have one. During development, you may use the Paddle Sandbox.

Add Paddle credentials

Paddle credentials are stored inside config/paddle.ts:

// config/paddle.ts

import Env from '@ioc:Adonis/Core/Env'

export default {
  vendorId: Env.get('PADDLE_VENDOR_ID'),
  authCode: Env.get('PADDLE_VENDOR_AUTH_CODE'),
  publicKey: Env.get('PADDLE_PUBLIC_KEY'),
  sandbox: Env.get('PADDLE_SANDBOX', false),
  vendorsUrl: Env.get('PADDLE_SANDBOX')
    ? 'https://sandbox-vendors.paddle.com/api/2.0'
    : 'https://vendors.paddle.com/api/2.0',
}
  • vendorId: This is your Paddle vendor ID.
  • authCode: This is your Paddle authentication code.
  • publicKey: This is your Paddle public key. This is required for verifying Paddle's webhooks.
  • sandbox: A boolean to indicate your application is using Paddle sandbox.
  • vendorsUrl: Paddle vendor API base URL depending on whether your application is using Paddle sandbox or not.

You can grab these credentials from your Paddle dashboard from the Authentication and Public Key sections under Developer Tools. These credentials should be added in your application's .env file:

// .env

PADDLE_VENDOR_ID=YOUR_PADDLE_VENDOR_ID
PADDLE_VENDOR_AUTH_CODE=YOUR_PADDLE_VENDOR_AUTH_CODE
PADDLE_SANDBOX=true
PADDLE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAykW3Mgcx9B20fPhARfh1...EAAQ==
-----END PUBLIC KEY-----"

If you're using Paddle's sandbox environment, you should set PADDLE_SANDBOX to true.

Plans

Before you can start billing your users, you need to first create plans that they can subscribe to. To create a plan, you need to first head over to your Paddle account and create the plans. Then in your admin area, you can provide the following details to create the respective plans:

  • Name: the name of the plan
  • Description: an optional description of the plan
  • Plan ID: plan ID from Paddle
  • Price: the price for the plan
  • Interval: the plan interval which should match that of the plan created on Paddle.
  • Incentive: an optional plan incentive such as "best value", "popular", "save 40%", etc.
  • Features: a comma-separated list of features included in the plan.

Paddle Webhooks

To be notified when events occur on Paddle and fulfill them accordingly on your application, you need to configure your application to receive webhooks from Paddle. That way, your application's billing data is in sync with Paddle's.

In your Paddle dashboard, go to Developer Tools > Events then under the Receiving events panel, enter https://project_name.com/webhook.

Where `project_name.com` is your application domain or the site sharing URL generated.

Also, you should enable webhook alerts for the following events:

  • Subscription Created
  • Subscription Updated
  • Subscription Cancelled
  • Subscription Payment Success
  • Subscription Payment Failed

Webhooks in local development

For Paddle to be able to send your application webhooks during local development, you will need to expose your application to be publically available. You can do that using site sharing services such as Ngrok or Expose.

Disabling billing

By default, billing is enabled in Pace but if billing functionality doesn't apply to your application or you don't need it yet, you can disable it in config/pace.ts:

 billing: false,

Also, enable to remove all Paddle environment variables references inside the env.ts file.

Upgrading Stripe