Add in-admin refund processing via Square RefundPayment API

admin/order.php previously had no real refund action - the "refunded"
status option was purely cosmetic, only setting order_status without
touching payment_status or calling any payment API. Adds a Refund card
(full or partial amount, optional reason) that calls the real Square
Refunds API for orders paid via Square, updates payment_status
(refunded/partially_refunded) and order_status, logs the refund ID as an
order note, and restores any wallet_amount_used back to the customer
wallet on a full refund (mirroring how it was deducted on payment
success in markSquarePaymentResult). Also fixed the Payment sidebar card
to display square_payment_id (it only ever showed the old stripe_payment_intent
field, even for Square orders).

Tested in sandbox: full refund (wallet restore verified), and confirmed
Squares own over-refund rejection surfaces cleanly as a flash error
rather than a crash.

admin/order.php

@@ -5,6 +5,7 @@
 ob_start();
 $pageTitle = 'Order Details';
 require_once __DIR__ . '/includes/header.php';
+require_once __DIR__ . '/../includes/square.php';
 
 $orderId = $_GET['id'] ?? '';
 
@@ -53,12 +54,87 @@ if ($_SERVER['REQUEST_METHOD'] === 'POST') {
             exit;
         }
     }
+
+    if ($action === 'process_refund') {
+        $refundAmount = (float) ($_POST['refund_amount'] ?? 0);
+        $reason = trim($_POST['refund_reason'] ?? '');
+
+        if ($order['payment_method'] !== 'square' || empty($order['square_payment_id'])) {
+            setFlash('error', 'This order has no Square payment to refund.');
+            header('Location: /admin/order.php?id=' . $orderId);
+            exit;
+        }
+        if ($order['payment_status'] !== 'paid' && $order['payment_status'] !== 'partially_refunded') {
+            setFlash('error', 'Only paid orders can be refunded.');
+            header('Location: /admin/order.php?id=' . $orderId);
+            exit;
+        }
+        if ($refundAmount <= 0 || $refundAmount > (float) $order['total']) {
+            setFlash('error', 'Invalid refund amount.');
+            header('Location: /admin/order.php?id=' . $orderId);
+            exit;
+        }
+
+        try {
+            $result = squareRefundPayment($order['square_payment_id'], $refundAmount, $reason ?: ('Order #' . $order['order_number']));
+            $refund = $result['refund'] ?? [];
+            $refundStatus = $refund['status'] ?? '';
+
+            if (in_array($refundStatus, ['PENDING', 'COMPLETED'], true)) {
+                $isFullRefund = $refundAmount >= (float) $order['total'];
+                $newPaymentStatus = $isFullRefund ? 'refunded' : 'partially_refunded';
+
+                db()->update('orders',
+                    ['payment_status' => $newPaymentStatus, 'order_status' => $isFullRefund ? 'refunded' : $order['order_status']],
+                    'order_id = :id',
+                    ['id' => $orderId]
+                );
+
+                // Restore any wallet credit that was applied, proportionally on a full refund
+                if ($isFullRefund && !empty($order['wallet_amount_used']) && (float) $order['wallet_amount_used'] > 0 && !empty($order['customer_id'])) {
+                    $walletAmount = (float) $order['wallet_amount_used'];
+                    $cust = db()->fetch("SELECT wallet_balance FROM customers WHERE customer_id = :id", ['id' => $order['customer_id']]);
+                    if ($cust) {
+                        $newBalance = (float) $cust['wallet_balance'] + $walletAmount;
+                        db()->update('customers', ['wallet_balance' => $newBalance], 'customer_id = :id', ['id' => $order['customer_id']]);
+                        db()->insert('wallet_transactions', [
+                            'transaction_id' => generateId('wt_'),
+                            'customer_id'    => $order['customer_id'],
+                            'amount'         => $walletAmount,
+                            'balance_after'  => $newBalance,
+                            'type'           => 'refund',
+                            'description'    => 'Refund for Order #' . $order['order_number'],
+                        ]);
+                    }
+                }
+
+                $existingNotes = $order['notes'] ?? '';
+                $newNote = '[' . date('M j, Y g:i A') . '] Refunded ' . formatCurrency($refundAmount)
+                    . ' via Square (refund ID: ' . ($refund['id'] ?? 'unknown') . ')'
+                    . ($reason ? ' — ' . $reason : '');
+                $allNotes = $existingNotes ? $existingNotes . "\n" . $newNote : $newNote;
+                db()->update('orders', ['notes' => $allNotes], 'order_id = :id', ['id' => $orderId]);
+
+                setFlash('success', formatCurrency($refundAmount) . ' refunded successfully.');
+            } else {
+                setFlash('error', 'Refund did not complete (status: ' . $refundStatus . ').');
+            }
+        } catch (Exception $e) {
+            setFlash('error', 'Refund failed: ' . $e->getMessage());
+        }
+
+        header('Location: /admin/order.php?id=' . $orderId);
+        exit;
+    }
 }
 
 $items = json_decode($order['items'], true) ?? [];
 $shippingAddress = json_decode($order['shipping_address'], true) ?? [];
 
 $statuses = ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'cancelled', 'refunded'];
+$canRefund = $order['payment_method'] === 'square'
+    && !empty($order['square_payment_id'])
+    && in_array($order['payment_status'], ['paid', 'partially_refunded'], true);
 ?>
 
 <div class="page-header">
@@ -81,6 +157,9 @@ $statuses = ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'canc
 <?php if (hasFlash('success')): ?>
     <div class="alert alert-success"><i class="fas fa-check-circle"></i> <?= getFlash('success') ?></div>
 <?php endif; ?>
+<?php if (hasFlash('error')): ?>
+    <div class="alert alert-error"><i class="fas fa-exclamation-circle"></i> <?= getFlash('error') ?></div>
+<?php endif; ?>
 
 <div style="display: grid; grid-template-columns: 2fr 1fr; gap: 1.5rem;">
     <!-- Main Column -->
@@ -141,6 +220,12 @@ $statuses = ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'canc
                                 <td style="text-align: right; color: var(--admin-success);">-<?= formatCurrency($order['discount']) ?></td>
                             </tr>
                         <?php endif; ?>
+                        <?php if (($order['wallet_amount_used'] ?? 0) > 0): ?>
+                            <tr>
+                                <td colspan="3" style="text-align: right;">Wallet / Gift Card</td>
+                                <td style="text-align: right; color: var(--admin-success);">-<?= formatCurrency($order['wallet_amount_used']) ?></td>
+                            </tr>
+                        <?php endif; ?>
                         <tr style="font-size: 1.125rem; font-weight: 600;">
                             <td colspan="3" style="text-align: right;">Total</td>
                             <td style="text-align: right;"><?= formatCurrency($order['total']) ?></td>
@@ -173,6 +258,32 @@ $statuses = ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'canc
                 </form>
             </div>
         </div>
+
+        <?php if ($canRefund): ?>
+        <!-- Refund -->
+        <div class="admin-card">
+            <div class="admin-card-header">
+                <h3 class="admin-card-title">Process Refund</h3>
+            </div>
+            <div class="admin-card-body">
+                <form method="POST" onsubmit="return confirm('Refund ' + document.getElementById('refund_amount').value + ' via Square? This cannot be undone.');">
+                    <input type="hidden" name="action" value="process_refund">
+                    <div class="form-group">
+                        <label class="form-label">Amount</label>
+                        <input type="number" step="0.01" min="0.01" max="<?= $order['total'] ?>" name="refund_amount" id="refund_amount" class="form-input" value="<?= $order['total'] ?>" required>
+                        <small class="text-muted">Up to <?= formatCurrency($order['total']) ?> (full order total). Enter a lower amount for a partial refund.</small>
+                    </div>
+                    <div class="form-group">
+                        <label class="form-label">Reason (optional)</label>
+                        <input type="text" name="refund_reason" class="form-input" placeholder="e.g. damaged item, customer request">
+                    </div>
+                    <button type="submit" class="btn btn-secondary btn-block">
+                        <i class="fas fa-undo"></i> Refund via Square
+                    </button>
+                </form>
+            </div>
+        </div>
+        <?php endif; ?>
     </div>
 
     <!-- Sidebar -->
@@ -260,13 +371,18 @@ $statuses = ['pending', 'confirmed', 'processing', 'shipped', 'delivered', 'canc
                     $paymentClass = match($order['payment_status']) {
                         'paid' => 'success',
                         'failed' => 'error',
-                        'refunded' => 'warning',
+                        'refunded', 'partially_refunded' => 'warning',
                         default => 'primary'
                     };
                     ?>
-                    <span class="badge badge-<?= $paymentClass ?>"><?= ucfirst($order['payment_status']) ?></span>
+                    <span class="badge badge-<?= $paymentClass ?>"><?= ucfirst(str_replace('_', ' ', $order['payment_status'])) ?></span>
                 </div>
-                <?php if ($order['stripe_payment_intent']): ?>
+                <?php if (!empty($order['square_payment_id'])): ?>
+                    <div style="display: flex; justify-content: space-between;">
+                        <span>Square Payment ID</span>
+                        <span class="text-muted" style="font-size: 0.8rem;"><?= htmlspecialchars(substr($order['square_payment_id'], 0, 20)) ?></span>
+                    </div>
+                <?php elseif ($order['stripe_payment_intent']): ?>
                     <div style="display: flex; justify-content: space-between;">
                         <span>Stripe ID</span>
                         <span class="text-muted" style="font-size: 0.8rem;"><?= htmlspecialchars(substr($order['stripe_payment_intent'], 0, 20)) ?>...</span>

includes/square.php

@@ -73,6 +73,21 @@ function squareGetPayment(string $paymentId): array {
     return squareApi('GET', '/payments/' . $paymentId);
 }
 
+function squareRefundPayment(string $paymentId, float $amount, string $reason = ''): array {
+    $body = [
+        'idempotency_key' => 'refund_' . $paymentId . '_' . bin2hex(random_bytes(6)),
+        'amount_money'    => [
+            'amount'   => (int) round($amount * 100),
+            'currency' => 'USD',
+        ],
+        'payment_id' => $paymentId,
+    ];
+    if ($reason) {
+        $body['reason'] = substr($reason, 0, 192);
+    }
+    return squareApi('POST', '/refunds', $body);
+}
+
 function isSquareConfigured(): bool {
     return defined('SQUARE_ACCESS_TOKEN') && defined('SQUARE_APP_ID') && defined('SQUARE_LOCATION_ID')
         && !empty(SQUARE_ACCESS_TOKEN) && !empty(SQUARE_APP_ID) && !empty(SQUARE_LOCATION_ID)