Pi SDK Rails

The pi-sdk-rails gem lets you quickly integrate the Pi Network payment/identity SDK into your Rails application. It automates nearly all the configuration and backend logic for a secure, full-stack Pi Network payments workflow, lifecycle callbacks, and user/transaction associations for your app.

The pi-sdk-rails gem is part of the “Ten Minutes to Transactions” effort described in this video.

If you are planning to use the Rails framework for your app, it is highly suggested that you use this gem rather than implement transaction processing by hand with the core Pi SDK. The three way handshake between client, server, and the Pi servers required is provded for you.

Rails Quick Start

Register your application with Pi Network

While this process is covered in the Getting Started Guide, here is a brief reminder of the steps you need to take. Application registration is also discussed in the video.

  • Open your Pi Mining app.
  • Click the hamburger (☰).
  • Select “Pi Utilities”.
  • Click the “Develop” icon followed by the “New App” icon.
  • Provide name and description of your app and submit.
  • Then click the “Configuration” icon.
  • Set the app URL to something valid, but does not necessarily exist.
  • Set the development URL to be http://localhost:3000. The actual port is between you and your development server.
  • Submit your changes.
  • Get your API key.
  • Register a wallet for your app.

Add pi-sdk-rails to your Gemfile

You can follow these steps in the video for a Stimulus- or React-based frontend.

gem 'pi-sdk-rails', git: 'https://github.com/pi-apps/pi-sdk-rails.git'

Install and generate engine files

You can install either the Stimulus frontend or React.

bundle install
rails generate pi_sdk:install        # Stimulus Frontend
rails generate pi_sdk:install_react  # React Frontend

Set up your Pi API config

  • Make sure <script src="https://sdk.minepi.com/pi-sdk.js"></script> was added to your main app layout.
  • Configure config/pi_sdk.yml for your Pi developer/test/production URLs and settings.

Set up routes and buttons

To connect your “Buy” button to the Pi payment flow with:

  • Stimulus: target a <button> and add the Stimulus data-controller and data-action attributes expected by the generated controller.
  • React: use (or modify) the generated PiButton.jsx / component produced by rails generate pi_sdk:install_react.

Stimulus example view usage:

<div data-controller="pinetwork">
  <button type="button" class="btn" data-action="click->pinetwork#buy" data-pinetwork-target="buyButton" disabled>
    Buy
  </button>
</div>

Let your app know your API key

export PI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Run your app through the Sandbox browser

Start the local server from your Rails project’s root directory.

bin/dev # or rails s

Then visit https://sandbox.minepi.com/mobile-app-ui/app/your-app-name in your favorite browser.

It will ask you to provide an authorization code to the Pi Mining app. Click the link at the bottom of the Pi Utilities screen to bring up the form.

What This Provides

  • Stimulus controller/API endpoints/user+transaction models prebuilt
  • Pi payment lifecycle: approve, complete, cancel, error, and incomplete callbacks handled server-side
  • Automatic user association: pi_username and order references
  • Your database is kept in sync with all Pi payment events
  • All Pi SDK config in YAML and environment variables. WARNING: never commit secrets
  • React/jsbundling integration generator: For modern JS apps, use rails generate pi_sdk:install_react instead — this skips importmaps and adds a ready-to-go Pi React button/component.

Key Details

  • Add Pi SDK <script src="https://sdk.minepi.com/pi-sdk.js"></script> tag to your HTML.
  • Customize all payment/server logic: Override controller methods for transaction lifecycle as needed (see generated controller and docs).
  • Config: API keys and sensitive settings are never checked into git. Use config/pi_sdk.yml and ENV variables.
  • Rails 7 and 8 compatible.

Video Script

You can watch a video describing the entire process. The commands used in the video for both the Stimulus and React versions appear below.

# Create the app
rails new tmtt

cd tmtt

# Add the gem to the app
echo "gem 'pi-sdk-rails', git: 'https://github.com/pi-apps/pi-sdk-rails.git'" >> Gemfile
bundle install

# Generate the necessary local files
rails generate pi_sdk:install

# Set up an example button
# Create a view and controller
rails generate controller root index

# Make the root#index root for the app
sed -i '' -e "s/# root \".*\"/root to: 'root#index'/" config/routes.rb

# Add a Buy button to the end of the root#index page
cat - >> app/views/root/index.html.erb <<HTML
<div data-controller="pi-sdk">
<button type="button" class="btn btn-primary" data-action="click->pi-sdk#buy" disabled data-pi-sdk-target="buyButton">
Buy
</button>
</div>
HTML

# Make PI_API_KEY available
source ../secrets

# Run the app
bin/dev

# Add PiTransaction model to the app
rails generate model User email
rails generate model Order description:string
rails generate pi_sdk:pi_transaction

rake db:migrate

# Run the app
bin/dev
# Create the app
rails new tmtt

cd tmtt

# Add the gem to the app
echo "gem 'pi-sdk-rails', git: 'https://github.com/pi-apps/pi-sdk-rails.git'" >> Gemfile
bundle install

# Generate the necessary local files
rails generate pi_sdk:install_react

# Set up an example button
# Create a view and controller
rails generate controller root index

# Make the root#index root for the app
sed -i '' -e "s/# root \".*\"/root to: 'root#index'/" config/routes.rb

# Add a Buy button to the end of the root#index page
cat - >> app/views/root/index.html.erb <<HTML
<div id="pi-sdk" />
HTML

# Make PI_API_KEY available
source ../secrets

# Run the app
bin/dev

# Add PiTransaction model to the app

rails generate model User email
rails generate model Order description:string
rails generate pi_sdk:pi_transaction

rake db:migrate

# Run the app
bin/dev

FAQ

How do I record/reference users and orders?

  • The engine ties all transactions to a unique user (by pi_username) and an order/payment model you control.
  • Use provided generators to add migrations/models for unique Pi users and transactions.

Does this handle CORS, sandbox, and IFrame caveats?

  • Yes—sane defaults and config are provided for Pi browser requirements.

How do I test locally with the Pi Sandbox?

  • Set your Pi app’s dev/test URL to your local server (with ngrok for mobile testing).
  • Follow Pi’s developer portal setup and set ENV API key.
  • Sandbox/test network flows are handled out of the box.

This generator sets up React/Vite entrypoints, JSX components, and avoids importmap dependencies.

Further Resources