Setting up Paddle subscriptions

Here’s how to understand and configure Paddle subscriptions in Business Class.

Design

Subscriptions are implemented with Pay and primarily made to work with Paddle.

Paddle bundles all subscriptions under a single email address which is why every subscription is started and maintained with the user that started it. Inside Business Class the subscription is named after the team and managable by all teams owners.

Paddle

To set up Paddle, read the Paddle developer docs and Pay’s Paddle documentation. Since everything is prepared to work out-of-the-box, you’ll only need the following Paddle configuration as part of your credentials file:

paddle:
  vendor_id: xxxx
  vendor_auth_code: yyyy
  public_key_base64: MII...==
  environment: sandbox

To prepare public_key_base64, you can encode your public key as:

Base64.encode64(public_key)

Alternatively to Rails credentials, you can also set them up using environment variables:

paddle_public_key = OpenSSL::PKey::RSA.new(File.read("paddle.pem"))

ENV["PADDLE_VENDOR_ID"] = ""
ENV["PADDLE_VENDOR_AUTH_CODE"] = ""
ENV["PADDLE_PUBLIC_KEY_BASE64"] = Base64.encode64(paddle_public_key)
ENV["PADDLE_ENVIRONMENT"] = "sandbox"

For development, you need to create a sandbox environment separated from a production account. If you don’t set Paddle environment you can still test the application using the fake subscriptions.

To update your credentials:

$ RAILS_MASTER_KEY=... bin/rails credentials:edit --environment=development

The test environment doesn’t need any credentials set, only development (with a sandbox) and production need that.

Webhooks

Once done, set up the webhook path to /pay/webhooks/paddle.

https://example.org/pay/webhooks/paddle

If you want to test webhooks locally, you can use a tool like ngrok which will give you a public address:

$ ngrok http 3000
...
Forwarding  https://406b-80-250-28-104.eu.ngrok.io -> http://localhost:3000

Then use this address and add it to the Paddle Sandbox under Developer Tools -> Events:

https://406b-80-250-28-104.eu.ngrok.io/pay/webhooks/paddle

Make sure it’s a primary address.

Don’t forget to remove the following condition in teams#success:

# Webhook won't arrive so let's pretend things are well
create_fake_subscription if Rails.env.development?

For a production environment you also have to approve your domain names.

Sandbox

By default, the devise layout is configured to use the sandbox environment. Once you tested your subscriptions in the sandbox and are ready to go live, remove the following line:

# app/views/layouts/devise.html.erb
...
Paddle.Environment.set('sandbox');
...

Plans

After you create your plans in Paddle, it will be possible to subscribe to them as part of the create new team/space/organization flow.

  • Plans starts with trials which have status trialing and the attribute trial_ends_at set.

  • After trial is over, customer is charged and the status moves to active.

  • Active subscriptions can be paused and resumed both from the application or Paddle. However, the paused status is not reflected in Paddle where the subscription is still labeled active. Apart from changed status, paddle_paused_from is set for paused subscriptions.

  • Active, paused, and trialing subscriptions can be cancelled. Paddle’s status deleted is saved as canceled and the ends_at attribute is set.

Cancelled subscriptions cannot be resumed.

Free plans

You can offer your customers a free plan.

A super user can subscribe to a free plan as well as move existing customer to a free plan from the administration area.

To enable it globally, set the ENABLE_FREE_PLAN environment variable.

Sync

Pay webhooks should ensure that subscriptions are always synced. Nevertheless, you can always run the following Rake task to synchronize subscriptions’s state:

$ rails paddle:sync

Failed payments

It’s important to set up behaviour for failed payments. Choose pausing or cancelling the subscription.