This 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. It is part of the "Ten Minutes to Transactions" effort described in this video.
-
Add to your Gemfile:
gem 'pi-sdk-rails', git: 'https://github.com/pi-apps/pi-sdk-rails.git'
-
Install and generate engine files:
bundle install rails generate pi_sdk:install
-
Set up your Pi API config:
- Add
<script src="https://sdk.minepi.com/pi-sdk.js"></script>to your main app layout (if not added automatically). - Configure
config/pi_sdk.ymlfor your Pi developer/test/production URLs and settings.
- Add
-
Set up routes and buttons:
- 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>
- Example view usage:
-
** Register your application with Pi Network: ** 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 exists, and the development URL to be "http://localhost:3000" (actual port is up to you). Submit your changes.
-
** Provide the Pi API key as an environment variable: ** Click on the "API Key" icon to get the API key for your app.
export PI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -
** Register a wallet for your app: ** Click on the "Wallet" icon to select or create a wallet for use with your app.
-
** Run your app through the Sandbox browser: ** Start the local server.
bin/dev # or rails sVisit "https://sandbox.minepi.com/mobile-app-ui/app/your-app-name". 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.
- 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_usernameand order references - Your database is kept in sync with all Pi payment events
- All Pi SDK config in YAML and environment variables; never commit secrets
- React/jsbundling integration generator: For modern JS apps, use
rails generate pi_sdk:install_reactinstead — this skips importmaps and adds a ready-to-go Pi React button/component.
- Dev/test/production ready.
- Add Pi SDK
<script>tag to your HTML:<script src="https://sdk.minepi.com/pi-sdk.js"></script>
- 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.ymland ENV variables. - Rails 7 and 8 compatible.
You can watch a video describing the entire process. The commands used in the video for the Stimulus version 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 tha 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/devHere's are the commands used in the video for the React version.
# 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 tha 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/devUse provided Stimulus or React components. Target a <button> and add the appropriate Stimulus data-controller and data-action attributes, or use/modify the generated PiButton.jsx if using React.
- 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.
- Yes—sane defaults and config are provided for Pi browser requirements.
- 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.
Absolutely! Use:
rails generate pi_sdk:install_reactThis generator sets up React/Vite entrypoints, JSX components, and avoids importmap dependencies.
- Official Pi SDK Docs
- Gem README & guides
- Your generated
app/controllers/pi_sdk/pi_payment_controller.rbfor server-side extension.