Documentation

Getting Started

Welcome to Flux! Our platform helps merchants automate Pi order confirmations by monitoring blockchain activity. Here's how it works:

Understanding Credits

Credits power Flux's order confirmation service:

How Credits Work

• Each credit confirms one order on the Pi blockchain
• When a customer pays, one credit is used to verify the transaction
• Credits never expire - they remain valid until used
• Purchase credits in bulk for volume discounts

Credit Usage Example

// Check your credit balance
const credits = await flux.credits.getBalance();
console.log(`Credits remaining: ${credits.available}`);

// Monitor credit usage
flux.on('credit.used', (event) => {
    console.log(`Credit used for order ${event.orderId}`);
    console.log(`Credits remaining: ${event.creditsRemaining}`);
});

Order Confirmation Flow

How Flux confirms orders through blockchain monitoring:

Code Example

// Create an order button
const button = await flux.buttons.create({
    amount: 10.0,
    merchantWallet: 'YOUR_PI_WALLET',  // Payments go directly here
    onOrderConfirmed: (transaction) => {
        console.log('Order confirmed!', transaction.amount);
        console.log('Transaction ID:', transaction.id);
        // Credit used for confirmation
        console.log('Credits remaining:', transaction.creditsRemaining);
    }
});

Authentication

All API requests require authentication. You can generate API keys from your Flux Developer Dashboard.

API Keys

Authentication is performed via HTTP Bearer Authentication. Include your API key in the Authorization header:

GET /v1/payments HTTP/1.1
Host: api.flux.io
Authorization: Bearer your_api_key_here
Content-Type: application/json

API Key Types

Flux provides two types of API keys:

Authentication Code Samples

// Using fetch API with authentication header
const fetchPayments = async () => {
  try {
    const response = await fetch('https://api.flux.io/v1/payments', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    
    console.log('Payments:', data);
    return data;
  } catch (error) {
    console.error('Error fetching payments:', error);
  }
};
fetchPayments();

# Using requests library with authentication header
import requests

def fetch_payments():
    try:
        headers = {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        }
        
        response = requests.get('https://api.flux.io/v1/payments', headers=headers)
        
        # Check if the request was successful
        response.raise_for_status()
        
        # Parse the JSON response
        data = response.json()
        
        print('Payments:', data)
        return data
    except Exception as error:
        print(f"Error fetching payments: {error}")
fetch_payments()

// Using cURL with authentication header
$ch = curl_init();

$headers = [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
];

curl_setopt($ch, CURLOPT_URL, 'https://api.flux.io/v1/payments');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode === 200) {
    $data = json_decode($response, true);
    
    echo 'Payments: ' . json_encode($data) . "\n";
    return $data;
}

curl_close($ch);
} catch (Exception $error) {
    echo 'Error fetching payments: ' . $error->getMessage();
}

Error Handling

The Flux API uses conventional HTTP response codes to indicate the success or failure of API requests. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with Flux's servers.

HTTP Status Codes

Error Response Format

When an error occurs, Flux returns a JSON object with error details:

{
  "error": {
    "code": "invalid_request",
    "message": "The provided API key is invalid",
    "docs_url": "https://docs.flux.io/errors#invalid_request",
    "param": null,
    "request_id": "req_7PtEBi4JMVb2Ef"
  }
}

Error Types

Flux API errors generally fall into the following categories:

Handling Errors

try {
  const payment = await flux.payments.create({
    amount: 10.0,
    currency: 'PI',
    description: 'Premium subscription'
  });
  // Handle successful payment
} catch (error) {
  if (error.type === 'authentication_error') {
    console.error('Authentication failed:', error.message);
    // Handle authentication error
  } else if (error.type === 'invalid_request') {
    console.error('Invalid request:', error.message);
    // Handle invalid parameters
  } else if (error.type === 'rate_limit_exceeded') {
    console.error('Rate limit exceeded. Try again later.');
    // Implement backoff strategy
  } else {
    console.error('Unexpected error:', error.message);
    // Handle other errors
  }
}

Order Confirmation API

Monitor Pi blockchain activity for order confirmations

Confirm an Order

Endpoint: POST /order/confirm

Request

{
  "amount": 10.0,
  "currency": "PI",
  "description": "Premium subscription",
  "merchant_wallet": "GD5YHQWSTDLU4I2TVSTTLVKXI3RDEOYMPC66EYS32JBPBTKWT4X2EWBW"
}
                

Response

{
  "order_id": "ord_8f7sd6f876dsf",
  "amount": 10.0,
  "status": "pending_confirmation",
  "created_at": "2025-05-27T22:45:13Z"
}
                

Verified Reviews API

Collect and display blockchain-verified customer feedback

Request a Review

Endpoint: POST /request

Request

{
  "order_id": "order_12345",
  "product_name": "Premium Subscription"
}
                

Sandbox Environment

The Flux Sandbox environment allows you to test your integration without processing real Pi transactions.

Sandbox API Keys

You can generate sandbox API keys from your Flux Developer Dashboard. These keys will only work with the sandbox API endpoints.

Testing Payments

In the sandbox environment, you can simulate successful payments using the following test Pi wallet:

# Test Pi Wallet Address for Sandbox
public_key: GD5YHQWSTDLU4I2TVSTTLVKXI3RDEOYMPC66EYS32JBPBTKWT4X2EWBW