Setting up Paddle subscriptions
Here’s how to understand and configure Paddle subscriptions in Business Class.
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.
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
public_key_base64, you can encode your public key as:
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.
Once done, set up the webhook path to
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:
Make sure it’s a primary address.
Don’t forget to remove the following condition in
# 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.
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'); ...
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
trialingand the attribute
After trial is over, customer is charged and the status moves to
Active subscriptions can be paused and resumed both from the application or Paddle. However, the
pausedstatus is not reflected in Paddle where the subscription is still labeled
active. Apart from changed status,
paddle_paused_fromis set for paused subscriptions.
Active, paused, and trialing subscriptions can be cancelled. Paddle’s status
deletedis saved as
ends_atattribute is set.
Cancelled subscriptions cannot be resumed.
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.
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
It’s important to set up behaviour for failed payments. Choose pausing or cancelling the subscription.