Skip to main content

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.

This guide demonstrates how to integrate the Pi SDK into a Rails app. This example shows how to initialize the Pi SDK, authenticate a Pioneer, and create a payment request inside a Pi app.

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

If you, or your GenAI agent, are planning to use the Rails 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.

Note: Pi SDK authentication and payment features require the application to run inside the Pi Browser.

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.

Bash

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.

Bash

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:

HTML

<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​

Bash

export PI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Run your app through the Sandbox browser​

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

Bash

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.

Authenticating Pi Users (Server-Side Token Verification)​

pi-sdk-rails manages the payment lifecycle but does not provide a token verification utility. You must implement GET /v2/me verification yourself in ApplicationController:

# app/controllers/application_controller.rb
def authenticate_pi_user!
  token = request.headers['Authorization']&.sub('Bearer ', '')&.strip
  return render json: { error: 'Unauthorized' }, status: :unauthorized unless token

  conn = Faraday.new(url: 'https://api.minepi.com') { |f| f.adapter Faraday::Adapter::NetHttp }
  response = conn.get('/v2/me') { |req| req.headers['Authorization'] = "Bearer #{token}" }
  return render json: { error: 'Invalid token' }, status: :unauthorized unless response.status == 200

  data = JSON.parse(response.body)
  @current_pi_user = PiUser.find_or_create_by(pi_uid: data['uid']) do |u|
    u.pi_username = data['username']
  end
end

Add gem 'faraday' and gem 'faraday-net_http' to your Gemfile. Call before_action :authenticate_pi_user! on any controller that needs a verified Pi user.

Note: Never pass the Pi API Key (Key <PI_API_KEY>) here — use Bearer <accessToken> for /v2/me. The API Key is only used for server-to-server payment calls handled by the gem.

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.

Stimulus

React

# 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​