> ## 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.

# List Payments

> Retrieve a paginated list of payment transactions with filtering and sorting options.

## Overview

This endpoint retrieves a list of payment transactions with support for pagination, filtering, and sorting. Results are ordered by creation date in descending order by default.

```bash theme={null}
GET /payments
```

## Query Parameters

<ParamField query="status" type="string">
  Filter by payment status.

  * Available values: `pending`, `captured`, `settled`, `failed`
  * Example: `status=settled`
</ParamField>

<ParamField query="before" type="string">
  Cursor for fetching records before a specific position.

  * Use for backward pagination
  * Example: `before=pay_123xyz`
</ParamField>

<ParamField query="after" type="string">
  Cursor for fetching records after a specific position.

  * Use for forward pagination
  * Example: `after=pay_456abc`
</ParamField>

<ParamField query="limit" type="integer" default="15">
  Number of records to return per page (max: 100).

  * Example: `limit=25`
</ParamField>

<ParamField query="created_after" type="string">
  Filter payments created after this timestamp (ISO 8601).

  * Example: `created_after=2024-01-01T00:00:00Z`
</ParamField>

<ParamField query="created_before" type="string">
  Filter payments created before this timestamp (ISO 8601).

  * Example: `created_before=2024-03-31T23:59:59Z`
</ParamField>

## Response Format

<ResponseField name="data" type="Payment[]">
  Array of payment objects. Each payment object contains:

  <Expandable title="Payment Object">
    <ResponseField name="id" type="string">
      Unique payment identifier
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Payment amount in minor units
    </ResponseField>

    <ResponseField name="currency" type="string">
      Three-letter currency code
    </ResponseField>

    <ResponseField name="status" type="string">
      Payment status (`pending`, `captured`, `settled`, `failed`)
    </ResponseField>

    <ResponseField name="customer" type="object">
      Customer details including name, email, and billing address
    </ResponseField>

    <ResponseField name="payment_method" type="object">
      Payment method details and type
    </ResponseField>

    <ResponseField name="date" type="string">
      Payment creation timestamp
    </ResponseField>

    <ResponseField name="order" type="object">
      Additional payment order
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <ResponseField name="before" type="string">
    Cursor for the previous page
  </ResponseField>

  <ResponseField name="after" type="string">
    Cursor for the next page
  </ResponseField>

  <ResponseField name="limit" type="integer">
    Number of records per page
  </ResponseField>
</ResponseField>

## Examples

### Basic List Request

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

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

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

  response = requests.get(
      'https://api.spendjuice.com/payments',
      params={'limit': 2},
      headers={'Authorization': ' YOUR_API_KEY'}
  )
  ```
</CodeGroup>

### Response Examples

<CodeGroup>
  ```json 200 Success theme={null}
  {
    "data": [
      {
        "auth_type": "3ds",
        "expires_at": "2024-03-01T08:43:08.110470Z",
        "links": {},
        "message": "Successful",
        "payment": {
          "amount": 50000,
          "cancellation_reason": null,
          "correlation_id": "2549dcf4-d743-11ee-9d95-c6d49632367b",
          "currency": "NGN",
          "customer": {
            "billing_address": {
              "city": "Awolowo Road",
              "country": "NG",
              "line1": "Opposite Sasa Estate",
              "line2": null,
              "state": "Kwara",
              "zip_code": "23401"
            },
            "email": "asajuenitan@gmail.com",
            "first_name": "Enitan",
            "id": "d05e51df-809e-498a-ac3f-7acfc0b5d35d",
            "last_name": "Michael",
            "phone_number": "+2348036120313"
          },
          "date": "2024-02-29T20:43:08.344264Z",
          "description": "Deposit",
          "id": "2549c96c-d743-11ee-aa4d-c6d49632367b",
          "order": {
            "identifier": "dbf99bd0-262a-46bd-8339-3c741d040dbb",
            "items": [
              {
                "name": "Deposit",
                "type": "digital"
              }
            ]
          }
          "mode": "live",
          "payment_method": {
            "card_number": "417396******9621",
            "expiry_month": 6,
            "expiry_year": 2024,
            "id": "5e21efda-c526-4057-92f6-1b94ee210b47",
            "type": "card"
          },
          "reference": "85d53ab5-92b8-4151-9f8f-a4f12863a911",
          "status": "settled"
        },
        "status": "settled"
      }
    ],
    "pagination": {
      "after": "2549c96c-d743-11ee-aa4d-c6d49632367b",
      "before": null,
      "limit": 2
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "Invalid query parameters",
      "details": {
        "limit": ["Must be between 1 and 100"]
      }
    }
  }
  ```
</CodeGroup>

## Pagination

The API uses cursor-based pagination to handle large collections of payments:

1. Initial request: Specify `limit` (default: 15)
2. Subsequent requests: Use the `after` cursor from the previous response
3. Previous page: Use the `before` cursor if available

<Note>
  For optimal performance:

  * Use reasonable page sizes (15-50 records)
  * Cache results when possible
  * Implement progressive loading in your UI
</Note>

## Filtering Tips

<AccordionGroup>
  <Accordion title="Status-based Filtering">
    ```bash theme={null}
    # Get all settled payments
    GET /payments?status=settled

    # Get failed payments from last 24 hours
    GET /payments?status=failed&created_after=2024-03-14T00:00:00Z
    ```
  </Accordion>

  <Accordion title="Date Range Filtering">
    ```bash theme={null}
    # Get payments for March 2024
    GET /payments?created_after=2024-03-01T00:00:00Z&created_before=2024-03-31T23:59:59Z
    ```
  </Accordion>
</AccordionGroup>

## Rate Limits

<Note>
  This endpoint has the following rate limits:

  * 1000 requests per hour per API key
  * Maximum of 100 records per request
  * Burst limit: 100 requests per minute
</Note>

## Best Practices

1. **Efficient Filtering**
   * Use filters to reduce response size
   * Combine filters for precise results
   * Cache frequently accessed data

2. **Pagination Handling**
   * Store cursors temporarily for navigation
   * Implement infinite scroll for large lists
   * Show loading states during fetches

3. **Error Handling**
   * Implement proper retry logic
   * Handle rate limits gracefully
   * Log pagination errors

<Card title="Need Help?">
  For additional assistance:

  * Review our [Error Handling Guide](/errors)
  * Contact [support@juicyway.com](mailto:support@juicyway.com)
</Card>