Performance Optimization

Learn how to optimize your Bridge Payments API usage for better performance and efficiency.

Include Parameter

The include parameter allows you to control which related resources are fetched with your API requests. This improves performance by only loading data when you actually need it.

Available for Endpoints

• GET /bridge-payment/payments - List payments

Supported Values

Value	Description	Impact
payment_method	Include payment method details (card brand, last 4 digits, expiry, wallet type, etc.)	+1 query per unique payment method

Usage Examples

Basic List (Fastest)

When you only need payment amounts and statuses:

GET /bridge-payment/payments?page=1&limit=20

Response:

{
  "success": true,
  "data": [
    {
      "id": "pay_123",
      "total_cents": 5500,
      "currency": "USD",
      "status": "succeeded",
      "payment_method_id": "pm_123",  // Only the ID
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Performance:

• ⚡ ~50ms response time
• 📦 ~5KB response size
• 🔍 1 database query

---

With Payment Method Details

When you need to show which card was used:

GET /bridge-payment/payments?page=1&limit=20&include=payment_method

Response:

{
  "success": true,
  "data": [
    {
      "id": "pay_123",
      "total_cents": 5500,
      "currency": "USD",
      "status": "succeeded",
      "payment_method_id": "pm_123",
      "payment_method": {  // Full details included
        "id": "pm_123",
        "payment_type": "card",
        "wallet_type": "apple_pay",
        "card_brand": "visa",
        "last_four": "4242",
        "expiry_month": "12",
        "expiry_year": "2025",
        "alias": "My Visa Card"
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Performance:

• ⚡ ~100ms response time
• 📦 ~15KB response size
• 🔍 1 + N database queries (optimized with parallel fetching)

---

Multiple Includes (Future)

The API is designed to support multiple includes in the future:

GET /bridge-payment/payments?include=payment_method,subscription,customer

---

Best Practices

✅ DO

• Use include only when needed: If you're building a simple payment history list, omit the parameter
• Combine with pagination: Use appropriate limit values to reduce data transfer
• Cache responses: Cache payment lists on the client side when appropriate
• Use filters: Combine include with status, search, and date filters to reduce result sets

❌ DON'T

• Always include everything: Only fetch what you need for the current view
• Fetch large pages with includes: Keep limit reasonable (20-50) when using include
• Ignore pagination: Always use pagination for lists

---

Performance Comparison

Scenario	Include Parameter	Response Time	Response Size	Use Case
Dashboard Overview	None	~50ms	~5KB	Show recent payments with amounts
Payment History	payment_method	~100ms	~15KB	Show which card was used for each payment
Detailed Report	payment_method	~150ms	~25KB	Export with all details

---

Code Examples

React Native

import { BridgePaymentAPI } from '@/lib/payments/api';

// Simple list for dashboard
const payments = await api.getPayments({
  page: 1,
  limit: 10
  // No include - faster response
});

// Detailed list with payment methods
const detailedPayments = await api.getPayments({
  page: 1,
  limit: 10,
  include: 'payment_method'  // Include card details
});

Next.js

// app/payments/page.tsx
async function PaymentsPage() {
  const payments = await fetch(
    '/bridge-payment/payments?page=1&limit=20&include=payment_method',
    {
      headers: {
        'X-Session-ID': sessionId
      }
    }
  );
  
  return <PaymentsList payments={payments.data} />;
}

---

Monitoring Performance

Track these metrics to optimize your API usage:

1. Response Time: Monitor average response times with/without include
2. Response Size: Track payload sizes to optimize bandwidth
3. Cache Hit Rate: Measure how often you can serve from cache
4. Query Count: Monitor database queries per request

---

Future Enhancements

Planned include options:

• subscription - Include subscription details for subscription payments
• customer - Include customer information
• address - Include billing address details
• refunds - Include refund information if applicable