Payments

This page is the reference for integrating Pi payments. Use the Pi SDK (window.Pi from https://sdk.minepi.com/pi-sdk.js) on the frontend and the Platform API on the backend.

For the conceptual three-phase flow, see Developer Payment Flow. For method signatures, see the Client SDK reference.

Implementation Workflow

Initialize the Pi SDK

Every Pi App must include the SDK script and call Pi.init() before any other SDK methods.

<head>
  <!-- ... other <head> content (meta, title, styles, etc.) ... -->
  <script src="https://sdk.minepi.com/pi-sdk.js"></script>
</head>

Pi.init({ version: "2.0", sandbox: true }); // use sandbox: false in production

Authenticate, then create a payment

Authenticate first (the payments scope is required). Then call Pi.createPayment with callbacks that forward paymentId and txid to your backend.

async function handleAuth() {
  try {
    const auth = await window.Pi.authenticate(
      ['username', 'payments'],
      onIncompletePayment
    );
    console.log(`User ${auth.user.username} is logged in.`);
    return auth;
  } catch (err) {
    console.error("Auth failed", err);
  }
}

function onIncompletePayment(payment) {
  // Send payment.identifier to your backend so it can complete the interrupted payment
}

function buyItem(accessToken) {
  window.Pi.createPayment(
    { amount: 1, memo: 'Unlock Premium', metadata: { feature: 'premium' } },
    {
      onReadyForServerApproval: async (paymentId) => {
        await fetch('/api/payments/approve', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`,
          },
          body: JSON.stringify({ paymentId }),
        });
      },
      onReadyForServerCompletion: async (paymentId, txid) => {
        const res = await fetch('/api/payments/complete', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${accessToken}`,
          },
          body: JSON.stringify({ paymentId, txid }),
        });
        if (res.ok) {
          // Deliver the purchased feature only after the backend confirms completion
        }
      },
      onCancel: (paymentId) => {
        console.log('Payment cancelled:', paymentId);
      },
      onError: (error, payment) => {
        console.error('Payment error:', error, payment);
      },
    }
  );
}

Handling Payments on the Backend

Your backend must call the Pi Platform API with your Server API Key. Never expose that key in client-side code.

const express = require('express');
const app = express();
app.use(express.json());

const PI_API_BASE = 'https://api.minepi.com/v2';
const PI_API_KEY = process.env.PI_API_KEY;

app.post('/api/payments/approve', async (req, res) => {
  const { paymentId } = req.body;
  try {
    const approval = await fetch(`${PI_API_BASE}/payments/${paymentId}/approve`, {
      method: 'POST',
      headers: { Authorization: `Key ${PI_API_KEY}` },
    });
    res.status(approval.status).json(await approval.json());
  } catch (err) {
    res.status(500).send(err.message);
  }
});

app.post('/api/payments/complete', async (req, res) => {
  const { paymentId, txid } = req.body;
  try {
    const completion = await fetch(`${PI_API_BASE}/payments/${paymentId}/complete`, {
      method: 'POST',
      headers: {
        Authorization: `Key ${PI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ txid }),
    });
    const data = await completion.json();
    if (completion.ok) {
      // Deliver the purchased feature here, using verified payment data
    }
    res.status(completion.status).json(data);
  } catch (err) {
    res.status(500).send(err.message);
  }
});

The same handshake applies in any backend language: POST /v2/payments/{paymentId}/approve then POST /v2/payments/{paymentId}/complete with { "txid": "<txid>" }. See the Platform API reference.

The frontend–backend handshake

A payment only settles if the frontend trigger and the backend validator stay in step:

1. Frontend (Pi.createPayment): Starts the payment. The SDK provides a paymentId via onReadyForServerApproval.
2. Handshake: The frontend sends the paymentId to your backend.
3. Backend (Platform API): Approves the payment with Pi Servers (POST /v2/payments/{paymentId}/approve).
4. Blockchain: The user signs the transaction; the frontend receives a txid via onReadyForServerCompletion.
5. Finalize: The backend completes the transaction (POST /v2/payments/{paymentId}/complete) and then delivers the purchased feature.

Implementation checklist

When adding Pi payments to an app:

1. Load https://sdk.minepi.com/pi-sdk.js and call Pi.init() before any other SDK methods.
2. Authenticate with Pi.authenticate(['username', 'payments'], onIncompletePaymentFound).
3. Create payments with Pi.createPayment(paymentData, callbacks). Wire onReadyForServerApproval and onReadyForServerCompletion to your backend.
4. Implement backend endpoints that call the Platform API with Authorization: Key <PI_API_KEY>. Store the key in environment variables; never hardcode credentials.
5. Always include a check for incomplete payments during the initial auth phase.
6. Deliver purchased features only after the backend receives a successful /complete response from Pi.
7. Include the CDN script in every environment, including production. The Pi Browser does not inject window.Pi for you.

Next

For App-to-User (A2U) payouts from your app to a Pioneer, see Advanced Payments.