Link Search Menu Expand Document
Pi Developer Guide

Quickstart

Overview

Looking to get a Pi app built? Check out the following steps to get set up and developing on Pi.
Creating a Pi App has 3 main parts: 1) create and configure the Pi App on your device via the Pi Browser Developer Portal, 2) create a web app using any web app develop framework you’d like to use, 3) integrate your Pi App shell with your web app.

Table of contents

Step 1: Getting the Pi Mining App and Registering for an Account

Before you do anything else, you need to install the Pi Mining App.

Google Play Store: https://play.google.com/store/apps/details?id=com.blockchainvault, or
App Store: https://itunes.apple.com/us/app/pi-network/id1445472541

Step 2: Getting the Pi Browser and Signing In

Next you need to download the Pi Browser, a mobile web browser which gives you access to all applications built using the Pi SDK.

Google Play Store: https://play.google.com/store/apps/details?id=pi.browser
Apple App Store: https://apps.apple.com/us/app/pi-browser/id1560911608

See our video tutorial to learn how to complete this

Step 3: Getting On The Developer Portal

Access the Pi Developer Portal using the Pi Browser. In the Pi Browser, navigate to pi://develop.pinet.com to visit the Pi Developer Portal. Alternatively, you can simply click on the ‘Develop’ menu icon on the Pi Browser Home page.
To register a new app, tap on the ‘New App’ button. To see information on an already created app, click on the tile for that app. This will bring you to the app’s dashboard page where you can see and edit information.

Step 4: Registering Your App

Fill in the required fields.

What you put for “App Name” will determine your App’s URL, so we advise using only letters, numbers, and spaces, and no special characters.

For “Description”, provide information on what your app does, what it would be used for, and some of its high-level features.

The ‘App Network’ option lets you select the host network that your app is connecting to. It’s important to select the network, either Pi Mainnet or Pi Testnet, that you wish to deploy on as the Pi SDK will automatically connect your app to the corresponding network. Note: that an app can only connect to one network at a time, and once you’ve registered the app, this option cannot be changed.

Step 5: Getting Your API Key

At the bottom of your project’s app dashboard on the Developer Portal, you can see a section called ‘API Key’. You will need it to access the Pi Backend as an application developer. Keep it safe! Anyone with this key can pretend to be you.

Step 6: Completing (most of) the Dev Portal Checklist

After you register your app, you can see the various details of your app via your app’s own ‘App Checklist’, which helps you keep track of required steps to successfully set up your app. To see the checklist, tap on the ‘App Checklist’ button located on the App Dashboard.

Step 7: Integrating Pi Into Your Application

The Pi SDK is javascript that you add to your page. First, call the SDK. Add this in the <head> of your page:

    <script src="https://sdk.minepi.com/pi-sdk.js"></script>
    <script> Pi.init({ version: "2.0", sandbox: true }) </script>

Next, authenticate the user. Add this in the <head> of your page:

<script> 
        // Authenticate the user, and get permission to request payments from them
        const scopes = ['payments','username'];

        // Read more about this callback in the SDK reference:
        function onIncompletePaymentFound(payment) { 
            console.log('incomplete payment found')
            paymentId = payment.identifier
            txid = payment.transaction.txid
            $.post('/payment/complete',
                    {
                        paymentId: paymentId,
                        txid: txid,
                        debug: 'cancel'
                    }
                )
        };
        Pi.authenticate(scopes, onIncompletePaymentFound).then(function(auth) {
          console.log(`Hi there! You're ready to make payments!`)
          const accessToken = auth.accessToken
        }).catch(function(error) {
          console.error(error);
        });
    </script>

In this code, onIncompletePaymentFound handles any pending payments from this authenticated user. You can select how you handle the payment: Cancel: Cancel, complete, or something else. Keep reading.

Step 8: Handling Payments

Finally - it’s time to handle payments! Payments have four steps. This section has everything you need, but understanding each step can help as you build more complex applications. To learn about each step, click here.

Step 8a: Create Payment

Use the createPayment function in the Pi SDK. This function takes two arguments: a paymentData object (which includes the amount to be paid, a memo for users, and metadata for your own usage) and an object of callback functions.

const paymentData = {
    amount: number,  /* Pi Amount being Transacted */
    memo: string, /* "Any information that you want to add to payment" */
    metadata: object {}, /* { Special Information: 1234, ... } */
};

// Callbacks the developer needs to implement:
const paymentCallbacks = {
    onReadyForServerApproval,
    onReadyForServerCompletion,
    onCancel,
    onError
    };

Pi.createPayment(paymentData, paymentCallbacks).then(function(payment) {
    console.log(payment)
  }).catch(function(error) {
    console.error(error);
  });

Step 8b: Server-Side Approval

The onReadyForServerApproval function gets called when the payment id is ready. Your app needs to pass the payment id and other relevant data to your app backend. The payment id should then be shared with the Pi API endpoint /payments/approve’ to signal that the app is ready to proceed with the payment.

const onReadyForServerApproval = (paymentId) => {
    console.log("onReadyForServerApproval", paymentId);
    axiosClient.post('/payments/approve', {paymentId}, config);
  }

Step 8c: User Interaction and Blockchain Transaction

The Pi browser shows the payment detail page to a user, and we are waiting until the user signs the transaction.

Step 8d: Server-Side Completion

The onReadyForServerCompletion function gets called after the blockchain transaction has been submitted to the Pi blockchain. Your job is again to pass any relevant data to your app server. On your server, you can verify the payment and deliver the item that was reserved for the user. In the end, you should complete the payment by letting the Pi server know that you have received the payment and delivered the item.

  const onReadyForServerCompletion = (paymentId, txid) => {
    console.log("onReadyForServerCompletion", paymentId, txid);
    axiosClient.post('/payments/complete', {paymentId, txid}, config);
  }

Please note that the actual implementation of these steps will depend on your specific app and server setup. Also, remember to handle any errors or cancellations that may occur during the payment process.

Additional Resources

Want to get more context on what your code could look like or what it could achieve. Head over to our Demo Apps and Blog to see other references including code examples.