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 attributetrial_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 labeledactive
. 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 ascanceled
and theends_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.