Overview

1. Simple Balance Check (API Key)

<?php
/**
 * Get account balance using API Key
 * Set RUSHPAY_API_KEY in the environment (e.g. .env loaded by your app — never commit secrets).
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY in the environment.\n");
    exit(1);
}

$ch = curl_init($apiBaseUrl . '/balances');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]
]);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);
    echo "Balance: " . number_format($data['data']['balance'], 2) . "\n";
} else {
    echo "Request failed (HTTP $httpCode).\n"; // Do not echo raw bodies in production (may leak details).
}

2. Get Balance with OAuth 2.0

<?php
/**
 * Get account balance using OAuth 2.0
 * Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET in the environment (never hard-code).
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$clientId = getenv('RUSHPAY_CLIENT_ID') ?: '';
$clientSecret = getenv('RUSHPAY_CLIENT_SECRET') ?: '';
if ($clientId === '' || $clientSecret === '') {
    fwrite(STDERR, "Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET.\n");
    exit(1);
}

// Step 1: Get access token
$ch = curl_init($apiBaseUrl . '/auth/login');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'client_id' => $clientId,
        'client_secret' => $clientSecret,
        'grant_type' => 'client_credentials'
    ])
]);

$response = curl_exec($ch);
$tokenData = json_decode($response, true);
curl_close($ch);

if (isset($tokenData['data']['access_token'])) {
    $accessToken = $tokenData['data']['access_token'];
    
    // Step 2: Get balance using access token
    $ch = curl_init($apiBaseUrl . '/balances');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $accessToken
        ]
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        $data = json_decode($response, true);
        echo "Balance: " . number_format($data['data']['balance'], 2) . "\n";
    }
} else {
    echo "Failed to get access token\n";
}

3. List Transactions

<?php
/**
 * List transactions with pagination
 * Production-ready example
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY.\n");
    exit(1);
}

// Get first page of transactions (10 per page)
$url = $apiBaseUrl . '/transactions?page=1&limit=10';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]
]);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);
    
    echo "Total Transactions: " . $data['data']['total'] . "\n";
    echo "Page: " . $data['data']['page'] . " of " . $data['data']['total_pages'] . "\n\n";
    
    foreach ($data['data']['transactions'] as $transaction) {
        echo "Reference: " . $transaction['reference'] . "\n";
        echo "Amount: " . number_format($transaction['amount'], 2) . "\n";
        echo "Type: " . $transaction['type'] . "\n";
        echo "Status: " . $transaction['status'] . "\n";
        echo "Date: " . $transaction['created_at'] . "\n";
        echo "---\n";
    }
} else {
    echo "Request failed (HTTP $httpCode).\n";
}

4. Create Payment Request

<?php
/**
 * Create a payment request (receive payment from RushPay user)
 * Production-ready example
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY.\n");
    exit(1);
}

// Amount stored here is what the payer will be charged (wallet / completion uses this value).
$paymentData = [
    'amount' => 100.00,
    'description' => 'Payment for Order #12345',
    'callback_url' => 'https://yoursite.com/payment-callback',
    'metadata' => [
        'order_id' => '12345',
        'customer_email' => '[email protected]'
    ]
];

$ch = curl_init($apiBaseUrl . '/payments/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($paymentData)
]);

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

if ($httpCode === 200 || $httpCode === 201) {
    $data = json_decode($response, true);
    echo "Payment Reference: " . $data['data']['payment_reference'] . "\n";
    echo "Next Step: Create widget session with this payment_reference (POST /v1/payments/widget-session)\n";
    echo "Status: " . $data['data']['status'] . "\n";
    echo "Expires At: " . $data['data']['expires_at'] . "\n";
} else {
    echo "Request failed (HTTP $httpCode).\n";
}

5. Complete Payment Page

Complete, production-ready payment page with RushPay Payment Widget integration. This example includes the full HTML page with widget integration, webhook handler, and callback URL examples.

<?php
/**
 * Production-Ready RushPay Payment Widget Example
 * 
 * This is a complete, production-ready example showing how to integrate
 * the RushPay Payment Widget into your website.
 * 
 * SETUP INSTRUCTIONS:
 * 1. Production: On your server, call POST /v1/payments/create (with Idempotency-Key) then
 *    POST /v1/payments/widget-session. Pass widget_session_token and payment_reference into this
 *    page (e.g. RUSHPAY_WIDGET_SESSION_TOKEN + RUSHPAY_PAYMENT_REFERENCE from your app session).
 *    Never put the merchant API key in HTML or static JS.
 * 2. Replace API host if different; set callback URL; optional webhook URL.
 * 3. Customize styling to match your website.
 */

// Configuration
$rushpay_widget_session_token = getenv('RUSHPAY_WIDGET_SESSION_TOKEN') ?: '';
$rushpay_payment_reference = getenv('RUSHPAY_PAYMENT_REFERENCE') ?: '';
if ($rushpay_widget_session_token === '' || $rushpay_payment_reference === '') {
    http_response_code(500);
    echo 'RushPay is not configured. Set RUSHPAY_WIDGET_SESSION_TOKEN and RUSHPAY_PAYMENT_REFERENCE.';
    exit;
}
$rushpay_api_base = 'https://api.rushpay.cash'; // RushPay API base URL
$rushpay_widget_base = 'https://api.rushpay.cash'; // RushPay widget base URL

// Payment Configuration
$payment_config = [
    // Amount configuration - choose one:
    'amount' => [
        'type' => 'fixed', // Options: 'fixed', 'default', or 'user-input'
        'value' => 100.00  // Required if type is 'fixed' or 'default'
    ],
    
    // Callback URL - where to redirect after successful payment
    'callback_url' => 'https://yoursite.com/payment-success?order_id=12345',
    
    // Webhook URL - optional, for server-side notifications
    'webhook_url' => 'https://yoursite.com/webhook/rushpay',
    
    // Payment description
    'description' => 'Payment for Order #12345'
];

// Get order ID from query string (example)
$order_id = $_GET['order_id'] ?? '12345';

// Update callback URL with order ID
$payment_config['callback_url'] = 'https://yoursite.com/payment-success?order_id=' . urlencode($order_id);
$payment_config['description'] = 'Payment for Order #' . htmlspecialchars($order_id);

// Optional: Get amount from query string or form
if (isset($_GET['amount']) && is_numeric($_GET['amount'])) {
    $amount = (float)$_GET['amount'];
    if ($amount > 0 && $amount <= 50000) {
        $payment_config['amount']['value'] = $amount;
    }
}
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Complete Payment - RushPay</title>
    
    <!-- RushPay Payment Widget CSS -->
    <link rel="stylesheet" href="<?php echo htmlspecialchars($rushpay_widget_base); ?>/widget/payment-widget.css">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
    
    <style>
        /* Custom styles for your page */
        body {
            font-family: 'SF Pro Display', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
            background: linear-gradient(135deg, #f5f5f5 0%, #e0e0e0 100%);
            min-height: 100vh;
            padding: 40px 20px;
            margin: 0;
        }

        .checkout-container {
            max-width: 1200px;
            margin: 0 auto;
        }

        .checkout-header {
            text-align: center;
            margin-bottom: 40px;
        }

        .checkout-header h1 {
            color: #333;
            font-size: 32px;
            margin-bottom: 10px;
        }

        .checkout-header p {
            color: #666;
            font-size: 16px;
        }

        .checkout-content {
            display: grid;
            grid-template-columns: 1fr 1fr;
            gap: 40px;
        }

        @media (max-width: 768px) {
            .checkout-content {
                grid-template-columns: 1fr;
            }
        }

        .order-summary {
            background: white;
            border-radius: 12px;
            padding: 24px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            height: fit-content;
        }

        .order-summary h2 {
            color: #333;
            font-size: 20px;
            margin-bottom: 20px;
            padding-bottom: 15px;
            border-bottom: 2px solid #f0f0f0;
        }

        .summary-item {
            display: flex;
            justify-content: space-between;
            padding: 12px 0;
            border-bottom: 1px solid #f0f0f0;
        }

        .summary-item:last-child {
            border-bottom: none;
            font-weight: 600;
            font-size: 18px;
            color: #ff6b00;
            margin-top: 10px;
            padding-top: 20px;
            border-top: 2px solid #f0f0f0;
        }

        .summary-label {
            color: #666;
        }

        .summary-value {
            color: #333;
            font-weight: 500;
        }

        .payment-section {
            background: white;
            border-radius: 12px;
            padding: 24px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
        }

        .payment-section h2 {
            color: #333;
            font-size: 20px;
            margin-bottom: 20px;
        }

        .security-badge {
            display: flex;
            align-items: center;
            gap: 8px;
            margin-top: 20px;
            padding: 12px;
            background: #f9f9f9;
            border-radius: 8px;
            font-size: 14px;
            color: #666;
        }

        .security-badge i {
            color: #28a745;
        }

        .rushpay-spinner {
            width: 40px;
            height: 40px;
            border: 4px solid #f3f3f3;
            border-top: 4px solid #ff6b00;
            border-radius: 50%;
            animation: spin 1s linear infinite;
            margin: 0 auto;
        }

        @keyframes spin {
            0% { transform: rotate(0deg); }
            100% { transform: rotate(360deg); }
        }
    </style>
</head>
<body>
    <div class="checkout-container">
        <div class="checkout-header">
            <h1><i class="fas fa-shopping-cart"></i> Complete Your Payment</h1>
            <p>Secure payment powered by RushPay</p>
        </div>

        <div class="checkout-content">
            <!-- Order Summary -->
            <div class="order-summary">
                <h2>Order Summary</h2>
                
                <div class="summary-item">
                    <span class="summary-label">Order ID:</span>
                    <span class="summary-value">#<?php echo htmlspecialchars($order_id); ?></span>
                </div>
                
                <div class="summary-item">
                    <span class="summary-label">Description:</span>
                    <span class="summary-value"><?php echo htmlspecialchars($payment_config['description']); ?></span>
                </div>
                
                <?php if ($payment_config['amount']['type'] === 'fixed' || $payment_config['amount']['type'] === 'default'): ?>
                <div class="summary-item">
                    <span class="summary-label">Amount:</span>
                    <span class="summary-value">GH₵<?php echo number_format($payment_config['amount']['value'], 2); ?></span>
                </div>
                <?php endif; ?>
                
                <div class="summary-item">
                    <span class="summary-label">Total:</span>
                    <span class="summary-value">
                        <?php if ($payment_config['amount']['type'] === 'fixed' || $payment_config['amount']['type'] === 'default'): ?>
                            GH₵<?php echo number_format($payment_config['amount']['value'], 2); ?>
                        <?php else: ?>
                            Enter amount
                        <?php endif; ?>
                    </span>
                </div>
            </div>

            <!-- Payment Widget -->
            <div class="payment-section">
                <h2>Payment Details</h2>
                
                <!-- RushPay Payment Widget Container -->
                <div id="rushpay-payment-widget">
                    <div style="padding: 20px; text-align: center; color: #666;">
                        <div class="rushpay-spinner" style="margin: 0 auto 10px;"></div>
                        <p>Loading payment widget...</p>
                    </div>
                </div>
                
                <div class="security-badge">
                    <i class="fas fa-shield-alt"></i>
                    <span>Your payment is secured and encrypted</span>
                </div>
            </div>
        </div>
    </div>

    <!-- RushPay Payment Widget JavaScript -->
    <?php
    // Build configuration for RushPay.init (widget-session checkout only)
    $jsConfig = [
        'widgetSessionToken' => $rushpay_widget_session_token,
        'paymentReference' => $rushpay_payment_reference,
        'callbackUrl' => $payment_config['callback_url'],
        'description' => $payment_config['description'],
    ];
    if (!empty($payment_config['webhook_url'])) {
        $jsConfig['webhookUrl'] = $payment_config['webhook_url'];
    }
    $jsConfigJson = json_encode($jsConfig, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    $apiBaseJson = json_encode($rushpay_api_base . '/v1', JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
    if ($jsConfigJson === false || json_last_error() !== JSON_ERROR_NONE) {
        $jsConfigJson = '{"callbackUrl":"","description":""}';
    }
    if ($apiBaseJson === false || json_last_error() !== JSON_ERROR_NONE) {
        $apiBaseJson = '"https://api.rushpay.cash/v1"';
    }
?><script>
        // Set API base URL before loading widget
        window.RUSHPAY_API_BASE = <?php echo $apiBaseJson; ?>;
        
        // Configuration object for widget initialization
        const rushpayConfig = <?php echo $jsConfigJson; ?>;

        var rushpayReady = (rushpayConfig.widgetSessionToken && rushpayConfig.paymentReference);
        if (!rushpayReady) {
            document.addEventListener('DOMContentLoaded', function() {
                document.getElementById('rushpay-payment-widget').innerHTML = 
                    '
' +
                    '
' +
                    'Configuration Error
' +
                    'Set widget session + payment reference in the PHP block at the top.' +
                    '
';
            });
        } else {
            // Load widget script
            const widgetScript = document.createElement('script');
            widgetScript.src = <?php echo json_encode($rushpay_widget_base . '/widget/payment-widget.js'); ?>;
            widgetScript.onload = function() {
                // Wait for DOM to be ready
                if (document.readyState === 'loading') {
                    document.addEventListener('DOMContentLoaded', initializeWidget);
                } else {
                    initializeWidget();
                }
            };
            widgetScript.onerror = function() {
                document.addEventListener('DOMContentLoaded', function() {
                    document.getElementById('rushpay-payment-widget').innerHTML = 
                        '
' +
                        '
' +
                        'Failed to Load Widget
' +
                        'Unable to load RushPay widget script. Please check the widget URL.' +
                        '
';
                });
            };
            document.head.appendChild(widgetScript);

            function initializeWidget() {
                // Check if RushPay is loaded
                if (typeof RushPay === 'undefined') {
                    console.error('RushPay widget failed to load');
                    document.getElementById('rushpay-payment-widget').innerHTML = 
                        '
' +
                        ' ' +
                        'RushPay widget object not found. Please check the script URL.' +
                        '
';
                    return;
                }

                try {
                    // Initialize RushPay Payment Widget
                    RushPay.init(rushpayConfig);
                } catch (error) {
                    console.error('RushPay initialization error:', error);
                    document.getElementById('rushpay-payment-widget').innerHTML = 
                        '
' +
                        '
' +
                        'Initialization Error
' +
                        error.message + '

' +
                        'Check the browser console (F12) for more details.' +
                        '
';
                }
            }
        }
    </script>
</body>
</html>

6. Giftcard/Voucher Support

<?php
/**
 * Process payment with giftcard/voucher redemption
 * Production-ready example
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY.\n");
    exit(1);
}

// Process payment with giftcard (pin required - user's 4-digit account PIN)
// Amount debited is the amount on the payment record from create, not a field here.
$paymentData = [
    'email' => '[email protected]',
    'payment_reference' => 'API-1234567890', // From create payment request
    'pin' => '1234', // User's 4-digit account PIN (required when confirming payment)
    'allow_giftcard' => true,
    'giftcard_code' => 'GIFTCARD123' // User's giftcard code
];

$ch = curl_init($apiBaseUrl . '/payments/process');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($paymentData)
]);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);
    
    if ($data['success']) {
        echo "Payment successful!\n";
        echo "Transaction ID: " . $data['data']['transaction_id'] . "\n";
        
        if (!empty($data['data']['giftcard_applied'])) {
            echo "Giftcard Applied: " . $data['data']['giftcard_applied'] . "\n";
            echo "Amount Paid (wallet portion): " . $data['data']['amount_paid'] . "\n";
        }
    } else {
        echo "Error: " . $data['message'] . "\n";
    }
} else {
    echo "Request failed (HTTP $httpCode).\n";
}

7. Send Payment to RushPay User

<?php
/**
 * Send payment to a RushPay user (refund, payout, etc.)
 * Production-ready example
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY.\n");
    exit(1);
}

$paymentData = [
    'recipient_account' => '1234567890', // OR use 'recipient_email' => '[email protected]'
    'amount' => 50.00,
    'description' => 'Refund for Order #12345'
];

$ch = curl_init($apiBaseUrl . '/payments/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($paymentData)
]);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);
    
    if ($data['success']) {
        echo "Payment sent successfully!\n";
        echo "Transaction ID: " . $data['data']['transaction_id'] . "\n";
        echo "Reference: " . $data['data']['reference'] . "\n";
        echo "Recipient: " . $data['data']['recipient_name'] . "\n";
    } else {
        echo "Error: " . $data['message'] . "\n";
    }
} else {
    echo "Request failed (HTTP $httpCode).\n";
}

8. Verify Payment Status

<?php
/**
 * Verify payment status (GET /v1/payments/verify?payment_reference=...)
 * Same as GET /v1/payments/{reference} — scoped to your API application via X-API-Key.
 */

$apiBaseUrl = 'https://api.rushpay.cash/v1';
$apiKey = getenv('RUSHPAY_API_KEY') ?: '';
if ($apiKey === '') {
    fwrite(STDERR, "Set RUSHPAY_API_KEY.\n");
    exit(1);
}
$paymentReference = 'API-1234567890'; // From create payment request

$ch = curl_init($apiBaseUrl . '/payments/verify?' . http_build_query(['payment_reference' => $paymentReference]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]
]);

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

if ($httpCode === 200) {
    $data = json_decode($response, true);

    echo "Payment Reference: " . $data['data']['payment_reference'] . "\n";
    echo "Status: " . $data['data']['status'] . "\n";
    echo "Amount: " . number_format($data['data']['amount'], 2) . "\n";

    if (($data['data']['status'] ?? '') === 'completed') {
        echo "Paid At: " . ($data['data']['paid_at'] ?? '') . "\n";
        echo "Transaction ID: " . ($data['data']['transaction_id'] ?? '') . "\n";
    }
} elseif ($httpCode === 429) {
    echo "Rate limited — retry later with backoff.\n";
} else {
    echo "Request failed (HTTP $httpCode).\n";
}

1. Simple Balance Check (API Key)

/**
 * Get account balance using API Key
 * Server-side only: load RUSHPAY_API_KEY from the environment (never expose in browser bundles).
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function getBalance() {
    try {
        const response = await axios.get(`${API_BASE_URL}/balances`, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        console.log('Balance:', response.data.data.balance.toFixed(2));
        return response.data.data.balance;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run
getBalance();

2. Get Balance with OAuth 2.0

/**
 * Get account balance using OAuth 2.0
 * Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET in the environment (never hard-code).
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const CLIENT_ID = process.env.RUSHPAY_CLIENT_ID;
const CLIENT_SECRET = process.env.RUSHPAY_CLIENT_SECRET;
if (!CLIENT_ID || !CLIENT_SECRET) throw new Error('Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET');

async function getBalanceWithOAuth() {
    try {
        // Step 1: Get access token
        const tokenResponse = await axios.post(`${API_BASE_URL}/auth/login`, {
            client_id: CLIENT_ID,
            client_secret: CLIENT_SECRET,
            grant_type: 'client_credentials'
        });
        
        const accessToken = tokenResponse.data.data.access_token;
        
        // Step 2: Get balance using access token
        const balanceResponse = await axios.get(`${API_BASE_URL}/balances`, {
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${accessToken}`
            }
        });
        
        console.log('Balance:', balanceResponse.data.data.balance.toFixed(2));
        return balanceResponse.data.data.balance;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run
getBalanceWithOAuth();

3. List Transactions

/**
 * List transactions with pagination
 * Production-ready example
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function listTransactions(page = 1, limit = 10) {
    try {
        const response = await axios.get(`${API_BASE_URL}/transactions`, {
            params: { page, limit },
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        const data = response.data.data;
        console.log(`Total Transactions: ${data.total}`);
        console.log(`Page: ${data.page} of ${data.total_pages}\n`);
        
        data.transactions.forEach(transaction => {
            console.log(`Reference: ${transaction.reference}`);
            console.log(`Amount: ${transaction.amount.toFixed(2)}`);
            console.log(`Type: ${transaction.type}`);
            console.log(`Status: ${transaction.status}`);
            console.log(`Date: ${transaction.created_at}`);
            console.log('---');
        });
        
        return data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run
listTransactions(1, 10);

4. Create Payment Request

/**
 * Create a payment request (receive payment from RushPay user).
 * `amount` is stored server-side — completion debits this value.
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function createPaymentRequest(amount, description, callbackUrl = '') {
    try {
        const response = await axios.post(`${API_BASE_URL}/payments/create`, {
            amount: amount,
            description: description,
            callback_url: callbackUrl,
            metadata: {
                order_id: '12345',
                customer_email: '[email protected]'
            }
        }, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        const data = response.data.data;
        console.log('Payment Reference:', data.payment_reference);
        console.log('Next Step: Create widget session with this payment_reference (POST /v1/payments/widget-session)');
        console.log('Status:', data.status);
        console.log('Expires At:', data.expires_at);
        
        return data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run
createPaymentRequest(100.00, 'Payment for Order #12345', 'https://yoursite.com/payment-callback');

5. Complete Payment Page

/**
 * Complete Payment Page - Full payment flow with OTP and giftcard support
 * Production-ready example - Node.js backend
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

/**
 * Make API request helper
 */
async function makeApiRequest(endpoint, method = 'GET', data = null) {
    const config = {
        method,
        url: `${API_BASE_URL}${endpoint}`,
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': API_KEY
        }
    };
    
    if (data && ['POST', 'PUT', 'PATCH'].includes(method)) {
        config.data = data;
    }
    
    try {
        const response = await axios(config);
        return {
            code: response.status,
            data: response.data
        };
    } catch (error) {
        return {
            code: error.response?.status || 500,
            data: error.response?.data || { success: false, message: error.message }
        };
    }
}

async function processCompletePayment() {
    // Step 1: Create Payment Request
    const payment = await makeApiRequest('/payments/create', 'POST', {
        amount: 100.00,
        description: 'Payment for Order #12345',
        callback_url: 'https://yoursite.com/payment-callback'
    });
    
    if (payment.code === 200 && payment.data.success) {
        const paymentReference = payment.data.data.payment_reference;
        
        // Step 2: Check if user exists
        const checkUser = await makeApiRequest('/payments/check-user', 'POST', {
            email: '[email protected]'
        });
        
        if (checkUser.data.success && checkUser.data.data.exists) {
            // Step 3: Send OTP (sent to user's email and SMS if they have a phone on file)
            const sendOtp = await makeApiRequest('/payments/send-otp', 'POST', {
                email: '[email protected]',
                payment_reference: paymentReference
            });
            
            if (sendOtp.data.success) {
                // Step 4: Verify OTP (user enters OTP code)
                const verifyOtp = await makeApiRequest('/payments/verify-otp', 'POST', {
                    email: '[email protected]',
                    otp_code: '123456', // User enters this
                    payment_reference: paymentReference
                });
                
                if (verifyOtp.data.success) {
                    const balance = verifyOtp.data.data.balance;
                    console.log('User Balance:', balance.toFixed(2));
                    
                    // Step 5: User confirms payment and enters 4-digit account PIN
                    // Step 6: Process Payment (pin required; optional giftcard)
                    const processPayment = await makeApiRequest('/payments/process', 'POST', {
                        email: '[email protected]',
                        payment_reference: paymentReference,
                        pin: '1234', // User's 4-digit account PIN (required)
                        allow_giftcard: true,
                        giftcard_code: '' // Optional: 'GIFTCARD123'
                    });
                    
                    if (processPayment.data.success) {
                        console.log('Payment successful!');
                        console.log('Transaction ID:', processPayment.data.data.transaction_id);
                    }
                }
            }
        }
    }
}

// Run
processCompletePayment();

6. Giftcard/Voucher Support

/**
 * Process payment with giftcard/voucher redemption
 * Production-ready example
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function processPaymentWithGiftcard(email, paymentReference, pin, giftcardCode) {
    try {
        const response = await axios.post(`${API_BASE_URL}/payments/process`, {
            email: email,
            payment_reference: paymentReference,
            pin: pin, // User's 4-digit account PIN (required)
            allow_giftcard: true,
            giftcard_code: giftcardCode
        }, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        if (response.data.success) {
            console.log('Payment successful!');
            console.log('Transaction ID:', response.data.data.transaction_id);
            
            if (response.data.data.giftcard_applied) {
                console.log('Giftcard Applied:', response.data.data.giftcard_applied);
                console.log('Amount Paid (wallet portion):', response.data.data.amount_paid);
            }
        } else {
            console.error('Error:', response.data.message);
        }
        
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run (pin = user's 4-digit account PIN; amount comes from the payment created earlier)
processPaymentWithGiftcard('[email protected]', 'API-1234567890', '1234', 'GIFTCARD123');

7. Send Payment to RushPay User

/**
 * Send payment to a RushPay user (refund, payout, etc.)
 * Production-ready example
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function sendPayment(recipientAccount, amount, description) {
    try {
        const response = await axios.post(`${API_BASE_URL}/payments/send`, {
            recipient_account: recipientAccount, // OR use recipient_email
            amount: amount,
            description: description
        }, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });
        
        if (response.data.success) {
            console.log('Payment sent successfully!');
            console.log('Transaction ID:', response.data.data.transaction_id);
            console.log('Reference:', response.data.data.reference);
            console.log('Recipient:', response.data.data.recipient_name);
        } else {
            console.error('Error:', response.data.message);
        }
        
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
}

// Run
sendPayment('1234567890', 50.00, 'Refund for Order #12345');

8. Verify Payment Status

/**
 * Verify payment status (GET /v1/payments/verify?payment_reference=...)
 */

const axios = require('axios');

const API_BASE_URL = 'https://api.rushpay.cash/v1';
const API_KEY = process.env.RUSHPAY_API_KEY;
if (!API_KEY) throw new Error('Set RUSHPAY_API_KEY in the environment');

async function verifyPayment(paymentReference) {
    try {
        const response = await axios.get(`${API_BASE_URL}/payments/verify`, {
            params: { payment_reference: paymentReference },
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': API_KEY
            }
        });

        const data = response.data.data;
        console.log('Payment Reference:', data.payment_reference);
        console.log('Status:', data.status);
        console.log('Amount:', Number(data.amount).toFixed(2));

        if (data.status === 'completed') {
            console.log('Paid At:', data.paid_at);
            console.log('Transaction ID:', data.transaction_id);
        }

        return data;
    } catch (error) {
        if (error.response?.status === 429) {
            console.error('Rate limited — retry later with backoff');
        } else {
            console.error('Error:', error.response?.data || error.message);
        }
        throw error;
    }
}

// Run
verifyPayment('API-1234567890');

1. Simple Balance Check (API Key)

"""
Get account balance using API Key
Load RUSHPAY_API_KEY from the environment (e.g. python-dotenv or host secrets).
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def get_balance():
    url = f"{API_BASE_URL}/balances"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    
    response = requests.get(url, headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        balance = data['data']['balance']
        print(f"Balance: {balance:.2f}")
        return balance
    else:
        print(f"Error: {response.text}")
        return None

# Run
get_balance()

2. Get Balance with OAuth 2.0

"""
Get account balance using OAuth 2.0
Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET in the environment (never hard-code).
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
CLIENT_ID = os.environ.get('RUSHPAY_CLIENT_ID')
CLIENT_SECRET = os.environ.get('RUSHPAY_CLIENT_SECRET')
if not CLIENT_ID or not CLIENT_SECRET:
    raise SystemExit('Set RUSHPAY_CLIENT_ID and RUSHPAY_CLIENT_SECRET')

def get_balance_with_oauth():
    # Step 1: Get access token
    token_url = f"{API_BASE_URL}/auth/login"
    token_data = {
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'grant_type': 'client_credentials'
    }
    
    token_response = requests.post(token_url, json=token_data)
    
    if token_response.status_code == 200:
        token_result = token_response.json()
        access_token = token_result['data']['access_token']
        
        # Step 2: Get balance using access token
        balance_url = f"{API_BASE_URL}/balances"
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {access_token}'
        }
        
        balance_response = requests.get(balance_url, headers=headers)
        
        if balance_response.status_code == 200:
            data = balance_response.json()
            balance = data['data']['balance']
            print(f"Balance: {balance:.2f}")
            return balance
        else:
            print(f"Error: {balance_response.text}")
    else:
        print(f"Failed to get access token: {token_response.text}")
    
    return None

# Run
get_balance_with_oauth()

3. List Transactions

"""
List transactions with pagination
Production-ready example
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def list_transactions(page=1, limit=10):
    url = f"{API_BASE_URL}/transactions"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    params = {'page': page, 'limit': limit}
    
    response = requests.get(url, headers=headers, params=params)
    
    if response.status_code == 200:
        data = response.json()['data']
        print(f"Total Transactions: {data['total']}")
        print(f"Page: {data['page']} of {data['total_pages']}\n")
        
        for transaction in data['transactions']:
            print(f"Reference: {transaction['reference']}")
            print(f"Amount: {transaction['amount']:.2f}")
            print(f"Type: {transaction['type']}")
            print(f"Status: {transaction['status']}")
            print(f"Date: {transaction['created_at']}")
            print("---")
        
        return data
    else:
        print(f"Error: {response.text}")
        return None

# Run
list_transactions(1, 10)

4. Create Payment Request

"""
Create a payment request (receive payment from RushPay user).
`amount` is stored server-side — completion debits this value.
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def create_payment_request(amount, description, callback_url=''):
    url = f"{API_BASE_URL}/payments/create"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    data = {
        'amount': amount,
        'description': description,
        'callback_url': callback_url,
        'metadata': {
            'order_id': '12345',
            'customer_email': '[email protected]'
        }
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    if response.status_code in [200, 201]:
        result = response.json()
        payment_data = result['data']
        print(f"Payment Reference: {payment_data['payment_reference']}")
        print("Next Step: Create widget session with this payment_reference (POST /v1/payments/widget-session)")
        print(f"Status: {payment_data['status']}")
        print(f"Expires At: {payment_data['expires_at']}")
        return payment_data
    else:
        print(f"Error: {response.text}")
        return None

# Run
create_payment_request(100.00, 'Payment for Order #12345', 'https://yoursite.com/payment-callback')

5. Complete Payment Page

"""
Complete Payment Page - Full payment flow with OTP and giftcard support
Production-ready example - Python backend
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def make_api_request(endpoint, method='GET', data=None):
    """Make API request helper"""
    url = f"{API_BASE_URL}{endpoint}"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    
    if method == 'GET':
        response = requests.get(url, headers=headers)
    elif method == 'POST':
        response = requests.post(url, headers=headers, json=data)
    else:
        return {'code': 405, 'data': {'success': False, 'message': 'Method not allowed'}}
    
    return {
        'code': response.status_code,
        'data': response.json() if response.text else {}
    }

def process_complete_payment():
    # Step 1: Create Payment Request
    payment = make_api_request('/payments/create', 'POST', {
        'amount': 100.00,
        'description': 'Payment for Order #12345',
        'callback_url': 'https://yoursite.com/payment-callback'
    })
    
    if payment['code'] == 200 and payment['data']['success']:
        payment_reference = payment['data']['data']['payment_reference']
        
        # Step 2: Check if user exists
        check_user = make_api_request('/payments/check-user', 'POST', {
            'email': '[email protected]'
        })
        
        if check_user['data']['success'] and check_user['data']['data']['exists']:
            # Step 3: Send OTP (sent to user's email and SMS if they have a phone on file)
            send_otp = make_api_request('/payments/send-otp', 'POST', {
                'email': '[email protected]',
                'payment_reference': payment_reference
            })
            
            if send_otp['data']['success']:
                # Step 4: Verify OTP (user enters OTP code)
                verify_otp = make_api_request('/payments/verify-otp', 'POST', {
                    'email': '[email protected]',
                    'otp_code': '123456',  # User enters this
                    'payment_reference': payment_reference
                })
                
                if verify_otp['data']['success']:
                    balance = verify_otp['data']['data']['balance']
                    print(f"User Balance: {balance:.2f}")
                    
                    # Step 5: User confirms payment and enters 4-digit account PIN
                    # Step 6: Process Payment (pin required; optional giftcard)
                    process_payment = make_api_request('/payments/process', 'POST', {
                        'email': '[email protected]',
                        'payment_reference': payment_reference,
                        'pin': '1234',  # User's 4-digit account PIN (required)
                        'allow_giftcard': True,
                        'giftcard_code': ''  # Optional: 'GIFTCARD123'
                    })
                    
                    if process_payment['data']['success']:
                        print("Payment successful!")
                        print(f"Transaction ID: {process_payment['data']['data']['transaction_id']}")

# Run
process_complete_payment()

6. Giftcard/Voucher Support

"""
Process payment with giftcard/voucher redemption
Production-ready example
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def process_payment_with_giftcard(email, payment_reference, pin, giftcard_code):
    url = f"{API_BASE_URL}/payments/process"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    data = {
        'email': email,
        'payment_reference': payment_reference,
        'pin': pin,  # User's 4-digit account PIN (required)
        'allow_giftcard': True,
        'giftcard_code': giftcard_code
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    if response.status_code == 200:
        result = response.json()
        if result['success']:
            print("Payment successful!")
            print(f"Transaction ID: {result['data']['transaction_id']}")
            
            if result['data'].get('giftcard_applied'):
                print(f"Giftcard Applied: {result['data']['giftcard_applied']}")
                print(f"Amount Paid (wallet portion): {result['data']['amount_paid']}")
        else:
            print(f"Error: {result['message']}")
        return result
    else:
        print(f"Error: {response.text}")
        return None

# Run (pin = user's 4-digit account PIN; amount comes from the payment created earlier)
process_payment_with_giftcard('[email protected]', 'API-1234567890', '1234', 'GIFTCARD123')

7. Send Payment to RushPay User

"""
Send payment to a RushPay user (refund, payout, etc.)
Production-ready example
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def send_payment(recipient_account, amount, description):
    url = f"{API_BASE_URL}/payments/send"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }
    data = {
        'recipient_account': recipient_account,  # OR use 'recipient_email'
        'amount': amount,
        'description': description
    }
    
    response = requests.post(url, headers=headers, json=data)
    
    if response.status_code == 200:
        result = response.json()
        if result['success']:
            print("Payment sent successfully!")
            print(f"Transaction ID: {result['data']['transaction_id']}")
            print(f"Reference: {result['data']['reference']}")
            print(f"Recipient: {result['data']['recipient_name']}")
        else:
            print(f"Error: {result['message']}")
        return result
    else:
        print(f"Error: {response.text}")
        return None

# Run
send_payment('1234567890', 50.00, 'Refund for Order #12345')

8. Verify Payment Status

"""
Verify payment status (GET /v1/payments/verify?payment_reference=...)
"""

import os
import requests

API_BASE_URL = 'https://api.rushpay.cash/v1'
API_KEY = os.environ.get('RUSHPAY_API_KEY')
if not API_KEY:
    raise SystemExit('Set RUSHPAY_API_KEY')

def verify_payment(payment_reference):
    url = f"{API_BASE_URL}/payments/verify"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
    }

    response = requests.get(url, headers=headers, params={'payment_reference': payment_reference})

    if response.status_code == 200:
        data = response.json()['data']
        print(f"Payment Reference: {data['payment_reference']}")
        print(f"Status: {data['status']}")
        print(f"Amount: {float(data['amount']):.2f}")

        if data['status'] == 'completed':
            print(f"Paid At: {data.get('paid_at')}")
            print(f"Transaction ID: {data.get('transaction_id')}")

        return data
    if response.status_code == 429:
        print("Rate limited — retry later with backoff")
        return None
    print(f"Error: {response.text}")
    return None

# Run
verify_payment('API-1234567890')