Pi Network Payments API Documentation

Test Values:
Testnet TxId: 2e161867201541d27ce138c0247e1e1c5208da96e0925851db97d368dcc52062
Testnet Payment ID: RKo9DyyzYmmnq4roS1infxy1qc4m

This API provides a secure interface to interact with Pi Network's payment system. The API supports both User-to-App (U2A) and App-to-User (A2U) payment directions.

Base URL

https://api.aloha-pi.com/v1/transaction

Authentication

All requests (except for details action) require authentication via Bearer token in the Authorization header:

Authorization: Bearer API_KEY

API Endpoints

All endpoints follow this pattern:

/v1/transaction/:direction/:action/:piPayId?/:piTxId?

Where:

Available Actions

User-to-App (U2A) Actions U2A

POST /v1/transaction/u2a/approve/:piPayId

Approve a payment from user to app.

Required: Payment ID

Required headers:

Authorization: Bearer API_KEY
Example:
fetch('https://api.aloha-pi.com/v1/transaction/u2a/approve/SOME_PAYMENT_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

POST /v1/transaction/u2a/complete/:piPayId/:piTxId

Complete a payment with transaction ID.

Required: Payment ID, Transaction ID (either in URL or request body)

Required headers:

Authorization: Bearer API_KEY
Example with txid in URL:
fetch('https://api.aloha-pi.com/v1/transaction/u2a/complete/SOME_PAYMENT_ID/SOME_TX_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})
Alternative with txid in request body:
fetch('https://api.aloha-pi.com/v1/transaction/u2a/complete/SOME_PAYMENT_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer API_KEY'
  },
  body: JSON.stringify({
    txid: 'SOME_TX_ID'
  })
})

POST /v1/transaction/u2a/abort/:piPayId

Handle user abort of payment.

Required: Payment ID

Required headers:

Authorization: Bearer API_KEY
Example:
fetch('https://api.aloha-pi.com/v1/transaction/u2a/abort/SOME_PAYMENT_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

GET /v1/transaction/u2a/details/:piPayId

Get payment details.

Required: Payment ID

Example:
fetch('https://api.aloha-pi.com/v1/transaction/u2a/details/SOME_PAYMENT_ID', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

App-to-User (A2U) Actions A2U

POST /v1/transaction/a2u/create

Create a new payment from app to user.

Required headers:

Content-Type: application/json
Authorization: Bearer API_KEY

Request body:

{
  "payment": {
    "amount": 1,
    "memo": "Payment for product XYZ",
    "metadata": {"orderId": "12345", "productId": "xyz-001"},
    "uid": "a1111111-aaaa-bbbb-2222-ccccccc3333d"
  }
}
Example:
fetch('https://api.aloha-pi.com/v1/transaction/a2u/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer API_KEY'
  },
  body: JSON.stringify({
    payment: {
      amount: 1,
      memo: "Payment for product XYZ",
      metadata: {orderId: "12345", productId: "xyz-001"},
      uid: "a1111111-aaaa-bbbb-2222-ccccccc3333d"
    }
  })
})

POST /v1/transaction/a2u/cancel/:piPayId

Cancel a pending payment.

Required: Payment ID

Required headers:

Authorization: Bearer API_KEY
Example:
fetch('https://api.aloha-pi.com/v1/transaction/a2u/cancel/SOME_PAYMENT_ID', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

GET /v1/transaction/a2u/incomplete

Get all incomplete payments.

Required headers:

Authorization: Bearer API_KEY
Example:
fetch('https://api.aloha-pi.com/v1/transaction/a2u/incomplete', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

GET /v1/transaction/a2u/details/:piPayId

Get payment details.

Required: Payment ID

Example:
fetch('https://api.aloha-pi.com/v1/transaction/a2u/details/SOME_PAYMENT_ID', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer API_KEY'
  }
})

Response Format

All responses follow this format:

Success Response

{
  "success": true,
  "action": "",
  "direction": "",
  "piResData": { ... },  // Payment data from Pi Network
  "sbResData": { ... }   // Database operation results (when applicable)
}

Error Response

{
  "success": false,
  "action": "",  // Only included if action was processed
  "direction": "",   // Only included if direction was processed
  "error": "Error message"
}

Notes