Setup with Pay

Add in-app purchases to your Rails app with the purchasekit gem.

This guide is for apps using the Pay gem. If you're not using Pay, see Standalone setup instead.

Installation

Add the gem to your Gemfile:

gem "purchasekit"

Run bundle install:

bundle install

The gem auto-detects Pay and enables integration automatically.

Configuration

Create an initializer at config/initializers/purchasekit.rb:

PurchaseKit.configure do |config|
  config.api_key = Rails.application.credentials.dig(:purchasekit, :api_key)
  config.app_id = Rails.application.credentials.dig(:purchasekit, :app_id)
  config.webhook_secret = Rails.application.credentials.dig(:purchasekit, :webhook_secret)
end

Add your credentials:

bin/rails credentials:edit

purchasekit:
  api_key: sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  app_id: app_XXXXXXXX
  webhook_secret: whsec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

You'll find these values in the PurchaseKit dashboard under Account → Developer.

Demo mode

For local development, you can use demo mode without PurchaseKit credentials:

PurchaseKit.configure do |config|
  config.demo_mode = Rails.application.credentials.dig(:purchasekit, :api_key).blank?
  # ... credentials
end

Demo mode simulates the purchase flow locally. Disable it in production by setting credentials.

Mount the engine

Add the engine to your routes:

# config/routes.rb
Rails.application.routes.draw do
  mount PurchaseKit::Engine, at: "/purchasekit"
  # ...
end

This adds:
- /purchasekit/webhooks - Receives webhooks from PurchaseKit
- /purchasekit/purchases - Creates purchase intents for the native app

JavaScript setup

Import the Turbo Stream actions for real-time redirects after purchase:

// app/javascript/application.js
import "purchasekit/turbo_actions"

Register the gem's Stimulus controllers:

// app/javascript/controllers/index.js
import { application } from "controllers/application"
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"

eagerLoadControllersFrom("controllers", application)
eagerLoadControllersFrom("purchasekit", application)

Set up Pay customer

Ensure your user model has a PurchaseKit payment processor:

# In your controller or concern
current_user.set_payment_processor(:purchasekit)

Next step

Build your paywall with the gem's view helpers.