> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Pay gem (Ruby on Rails)

Community-maintained Ruby on Rails gem that provides an abstraction over Paddle Billing alongside other payment processors.

---

[Pay](https://github.com/pay-rails/pay) is a community-maintained payments engine for Ruby on Rails 6.0 and later. It abstracts over Paddle Billing, Stripe, Braintree, and Lemon Squeezy with a single API for customers, subscriptions, charges, and webhooks.

{% callout type="info" %}
The pay gem is maintained by the [pay-rails](https://github.com/pay-rails) community, not by Paddle. For support, use the [Pay issue tracker](https://github.com/pay-rails/pay/issues).
{% /callout %}

{% card-group cols=3 %}
{% card title="GitHub" icon="carbon:logo-github" url="https://github.com/pay-rails/pay" %}
View source code and report issues on GitHub.
{% /card %}
{% card title="RubyGems" icon="ruby" url="https://rubygems.org/gems/pay" %}
View and install on RubyGems.
{% /card %}
{% card title="Changelog" icon="carbon:bullhorn" url="https://github.com/pay-rails/pay/blob/main/CHANGELOG.md" %}
See recent releases and changes.
{% /card %}
{% /card-group %}

## Requirements

- Ruby.
- Rails 7.0 or later.

## Install

Add Pay to your `Gemfile`:

```ruby
gem "pay", "~> 11.5"
gem "paddle", "~> 2.9"
```

Run `bundle install` and follow the [installation guide](https://github.com/pay-rails/pay/blob/main/docs/1_installation.md) to generate migrations and configure your User model.

## Configure

Pay reads Paddle credentials from environment variables, or the equivalent Rails credentials:

| Variable                        | Purpose                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `PADDLE_BILLING_ENVIRONMENT`    | `sandbox` or `production`. Defaults to `production`.                                        |
| `PADDLE_BILLING_API_KEY`        | API key from **Paddle > Developer tools > Authentication**.                                 |
| `PADDLE_BILLING_CLIENT_TOKEN`   | Client-side token for Paddle.js, created in the same place.                                 |
| `PADDLE_BILLING_SIGNING_SECRET` | Notification destination secret key, used to verify webhook signatures.                     |

## Quick example

Create a Paddle customer for a Pay-enabled model:

```ruby
user.set_payment_processor :paddle_billing
user.payment_processor.api_record
```

Subscriptions are created using webhooks. When Paddle sends a `subscription.created` notification, Pay creates the subscription record automatically. See the [subscriptions guide](https://github.com/pay-rails/pay/blob/main/docs/6_subscriptions.md) for more.

## Links

- [Paddle Billing guide in the Pay docs](https://github.com/pay-rails/pay/blob/main/docs/paddle_billing/1_overview.md)
- [Pay issue tracker](https://github.com/pay-rails/pay/issues)