> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Statistics

> Retrieve aggregate statistics about your payment transactions

## Overview

The Payment Statistics API provides aggregated metrics about your payment transactions across different statuses. This helps you monitor payment flows and track success/failure rates.

```http theme={null}
GET /payments/stats
```

## Authentication

<Note>
  All requests must include your API key in the Authorization header:

  ```bash theme={null}
  Authorization:  YOUR_API_KEY
  ```
</Note>

## Response Fields

<ResponseField name="data" type="object">
  Payment statistics container object.

  <Expandable title="Statistics Fields">
    <ResponseField name="captured" type="integer">
      Number of payments successfully captured but not yet settled
    </ResponseField>

    <ResponseField name="failed" type="integer">
      Number of failed payment attempts
    </ResponseField>

    <ResponseField name="pending" type="integer">
      Number of payments currently in progress
    </ResponseField>

    <ResponseField name="settled" type="integer">
      Number of payments fully completed and settled
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of payment attempts across all statuses
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Basic Statistics Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.spendjuice.com/payments/stats" \
  -H "Authorization:  YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.spendjuice.com/payments/stats',
      headers={'Authorization': ' YOUR_API_KEY'}
  )
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.spendjuice.com/payments/stats', {
    headers: {
      'Authorization': ' YOUR_API_KEY'
    }
  });
  ```
</CodeGroup>

### Success Response

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "data": {
      "captured": 2,
      "failed": 5,
      "pending": 2,
      "settled": 8,
      "total": 20
    }
  }
  ```

  ```json Empty Stats theme={null}
  {
    "data": {
      "captured": 0,
      "failed": 0,
      "pending": 0,
      "settled": 0,
      "total": 0
    }
  }
  ```
</CodeGroup>

## Data Aggregation

The statistics endpoint aggregates payment data with the following characteristics:

* Updates in near real-time as payment statuses change
* Includes payments from the last 30 days by default
* Counts each payment exactly once based on its current status
* Excludes test mode payments from production statistics

## Usage Examples

### Monitor Payment Success Rate

```javascript theme={null}
const stats = await getPaymentStats();
const successRate = (stats.data.settled / stats.data.total) * 100;
console.log(`Payment Success Rate: ${successRate}%`);
```

### Track Failed Payments

```javascript theme={null}
const stats = await getPaymentStats();
if (stats.data.failed > 0) {
  notifyTeam(`${stats.data.failed} failed payments require attention`);
}
```

## Best Practices

1. **Caching**
   * Cache statistics for up to 5 minutes to reduce API load
   * Implement stale-while-revalidate caching strategy
   * Clear cache when receiving payment webhooks

2. **Error Handling**
   * Implement exponential backoff for retries
   * Handle network timeouts gracefully
   * Log unusual statistical patterns

3. **Monitoring**
   * Track success rate trends over time
   * Set up alerts for unusual failure rates
   * Monitor pending payment resolution times

<Card title="Need Help?">
  For questions about payment statistics:

  * Review our [Error Handling](/errors) guide
  * Contact [support@juicyway.com](mailto:support@juicyway.com)
  * Join our [Discord community](https://discord.gg/juice)
</Card>