Core Pi SDK

The Pi SDK provides all of the functionality for your app to operate in the Pi Ecosystem. This page presumes that pi-sdk.js has been loaded into the browser.

• Initialization & Authentication
• Payment Flow

Pi SDK Instance

All methods below are called via window.Pi (not statically).

Core Methods

Initialization & Authentication

.init(options)

• Purpose: Initialize the SDK, typically called once application loads.
• Signature:

  window.Pi.init({ version: '2.0', sandbox?: boolean })
  

• Parameters:
  • version (string, required) – SDK protocol version
  • sandbox (boolean, optional)

.authenticate(scopes, onIncompletePaymentFound)

• Purpose: Requests user authentication via Pi Browser, and checks for incomplete payments.
• Signature:

  window.Pi.authenticate([
      'payments',           // Required for payment flows
      'username',           // Get user info
      'roles', 'wallet_address', ... // Additional scopes
    ], onIncompletePaymentFound)
    .then(({ user, accessToken }) => { ... });
  

• Parameters:
  • scopes (array of strings): Permissions to request (at least 'payments', 'username')
  • onIncompletePaymentFound (function, optional): Callback invoked if any unfinished payment should be handled
• Returns: Promise resolving to { user, accessToken }

Important: You must successfully authenticate the user before performing any user-related actions (for example, reading their info or initiating a payment). The first time a user authenticates, Pi Browser shows a consent dialog asking them to share their data with your app.

Payment Flow

.createPayment(paymentData, callbacks)

• Purpose: Initiates a Pi payment by sending a payment request from the current user to your app’s account.
  • What the user sees: A Pi Wallet modal opens on top of your app, prompting the user to review the payment details, sign the transaction, and submit it to the Pi Blockchain (or cancel the request).
• Signature:

  window.Pi.createPayment(paymentData, {
    onReadyForServerApproval: (paymentId) => { ... },
    onReadyForServerCompletion: (paymentId, txid) => { ... },
    onCancel: (paymentId) => { ... },
    onError: (error, paymentData) => { ... }
  });
  

• Parameters:
  • paymentData (object): Payment details, e.g. { amount, memo, metadata }
  • callbacks (object): Required handler functions (see above)

Looking for App-to-User (A2U) payouts?
Pi.createPayment covers User-to-App (U2A) flows. For payments from your app to users (A2U), use the Platform API from your backend. See Advanced Payments for details.

Callback Functions

• onReadyForServerApproval(paymentId) – Called when payment is ready for backend approval
• onReadyForServerCompletion(paymentId, txid) – Called when network waits for backend to mark complete
• onCancel(paymentId) – Payment canceled by user
• onError(error, paymentData) – Error in payment process
• onIncompletePaymentFound(paymentDTO) – (from .authenticate) handle unfinished payment

General Usage Example

<script src="/pi-sdk.js"></script>
<script>
  window.Pi.init({ version: "2.0", sandbox: true });
  window.Pi.authenticate(["payments", "username"], function onPaymentFound(payment) {
    // Handle an incomplete payment
  }).then(({ user, accessToken }) => {
    // Ready to make payments
    window.Pi.createPayment(
      { amount: 0.02, memo: "Pi Example", metadata: { order_id: 42 } },
      {
        onReadyForServerApproval: (paymentId) => {
          /* POST to /approve */
        },
        onReadyForServerCompletion: (paymentId, txid) => {
          /* POST to /complete */
        },
        onCancel: (paymentId) => {
          console.log("Canceled", paymentId);
        },
        onError: (error) => {
          console.error(error);
        },
      },
    );
  });
</script>

Access Point Summary Table

Functionality is inferred from SDK patterns, public documentation, and code inspection. Actual API may differ slightly depending on SDK version. Not all methods will be present/documented if not supported by a particular build.

For question about specific methods, advanced usage, or backend integration, see core SDK documentation or contact Pi Network developer support.