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

# List One-Time Payments

> Query and filter your organization payment links with pagination

## Overview

The List One-Time Payments endpoint allows you to retrieve all payment links created by your organization. You can filter results by status and currency, and use pagination to handle large datasets.

**Common use cases:**

* View all payment links in a dashboard
* Filter by payment status (PENDING, CONFIRMED, CANCELLED)
* Generate reports and reconciliation data
* Monitor payment activity across your organization

## Authentication

This endpoint requires API key authentication using the `x-api-key` header.

<Note>
  Your API key can be found in your organization settings. Keep it secure and never expose it in client-side code.
</Note>

## Query Parameters

<ParamField query="page" type="integer" default={1}>
  Page number for pagination. Must be a positive integer.
</ParamField>

<ParamField query="pageSize" type="integer" default={100}>
  Number of items to return per page. Must be between 1 and 500.
</ParamField>

<ParamField query="status" type="string" optional>
  Filter payments by status. Available values:

  * `PENDING` - Payment link is active and awaiting payment
  * `CONFIRMED` - Payment has been successfully completed
  * `CANCELLED` - Payment link has been cancelled
</ParamField>

<ParamField query="currency" type="string" optional>
  Filter payments by currency. Currently only `MXN` is supported.
</ParamField>

## Response Format

The endpoint returns a paginated response with the following structure:

```json theme={null}
{
  "count": 245,
  "page": 1,
  "pageSize": 100,
  "items": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "PENDING",
      "description": "Payment for order #1234",
      "amount": 100,
      "currency": "MXN",
      "externalId": "order-1234",
      "expiresAt": "2026-01-11T10:30:00Z",
      "redirectUrl": "https://example.com/success",
      "homepageUrl": "https://example.com",
      "createdAt": "2026-01-09T10:30:00Z",
      "updatedAt": "2026-01-09T10:30:00Z",
      "billingInformation": {
        "email": "maria.gonzalez@example.com",
        "firstName": "María",
        "lastName": "González",
        "phoneNumber": "+5215512345678",
        "address": {
          "addressLine": "Av. Insurgentes Sur 1234",
          "city": "Ciudad de México",
          "state": "CDMX",
          "zip": "03100"
        }
      }
    }
  ]
}
```

### Response Fields

* **count** - Total number of payments matching your filter criteria
* **page** - Current page number
* **pageSize** - Number of items per page
* **items** - Array of payment objects

## Examples

### List all payments

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.harmony.compago.com/api/one-time-payment' \
    -H 'x-api-key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.harmony.compago.com/api/one-time-payment', {
    method: 'GET',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(`Total payments: ${data.count}`);
  console.log(`Current page: ${data.page}/${Math.ceil(data.count / data.pageSize)}`);
  ```

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

  response = requests.get(
      'https://api.harmony.compago.com/api/one-time-payment',
      headers={'x-api-key': 'YOUR_API_KEY'}
  )

  data = response.json()
  print(f"Total payments: {data['count']}")
  print(f"Retrieved {len(data['items'])} payments")
  ```
</CodeGroup>

### Filter by status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?status=PENDING' \
    -H 'x-api-key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ status: 'PENDING' });
  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    {
      method: 'GET',
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }
  );

  const data = await response.json();
  console.log(`Pending payments: ${data.count}`);
  ```

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

  params = {'status': 'PENDING'}
  response = requests.get(
      'https://api.harmony.compago.com/api/one-time-payment',
      headers={'x-api-key': 'YOUR_API_KEY'},
      params=params
  )

  data = response.json()
  print(f"Pending payments: {data['count']}")
  ```
</CodeGroup>

### Pagination example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?page=2&pageSize=50' \
    -H 'x-api-key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  // Fetch all pages
  async function fetchAllPayments() {
    let allPayments = [];
    let page = 1;
    const pageSize = 100;

    while (true) {
      const params = new URLSearchParams({ page: page.toString(), pageSize: pageSize.toString() });
      const response = await fetch(
        `https://api.harmony.compago.com/api/one-time-payment?${params}`,
        {
          method: 'GET',
          headers: { 'x-api-key': 'YOUR_API_KEY' }
        }
      );

      const data = await response.json();
      allPayments = allPayments.concat(data.items);

      // Check if we've reached the last page
      if (page * pageSize >= data.count) {
        break;
      }

      page++;
    }

    return allPayments;
  }

  const payments = await fetchAllPayments();
  console.log(`Fetched ${payments.length} total payments`);
  ```

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

  def fetch_all_payments():
      all_payments = []
      page = 1
      page_size = 100

      while True:
          response = requests.get(
              'https://api.harmony.compago.com/api/one-time-payment',
              headers={'x-api-key': 'YOUR_API_KEY'},
              params={'page': page, 'pageSize': page_size}
          )

          data = response.json()
          all_payments.extend(data['items'])

          # Check if we've reached the last page
          if page * page_size >= data['count']:
              break

          page += 1

      return all_payments

  payments = fetch_all_payments()
  print(f"Fetched {len(payments)} total payments")
  ```
</CodeGroup>

### Filter by multiple parameters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.harmony.compago.com/api/one-time-payment?status=CONFIRMED&currency=MXN&page=1&pageSize=50' \
    -H 'x-api-key: YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    status: 'CONFIRMED',
    currency: 'MXN',
    page: '1',
    pageSize: '50'
  });

  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    {
      method: 'GET',
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }
  );

  const data = await response.json();
  console.log(`Confirmed MXN payments: ${data.count}`);
  ```

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

  params = {
      'status': 'CONFIRMED',
      'currency': 'MXN',
      'page': 1,
      'pageSize': 50
  }

  response = requests.get(
      'https://api.harmony.compago.com/api/one-time-payment',
      headers={'x-api-key': 'YOUR_API_KEY'},
      params=params
  )

  data = response.json()
  print(f"Confirmed MXN payments: {data['count']}")
  ```
</CodeGroup>

## Best Practices

<Tip>
  **Optimize page sizes** - Use appropriate page sizes for your use case. Smaller pages (10-50 items) for UI display, larger pages (100-500 items) for batch processing.
</Tip>

<Tip>
  **Filter when possible** - Use status and currency filters to reduce the dataset and improve query performance.
</Tip>

<Tip>
  **Handle pagination properly** - Always check the `count` field to determine the total number of pages available.
</Tip>

<Warning>
  The maximum page size is 500 items. Requests exceeding this limit will return a 400 error.
</Warning>

## Common Use Cases

### Dashboard View

Display recent payments with status filtering:

```javascript theme={null}
// Fetch the most recent pending payments for dashboard display
const params = new URLSearchParams({
  status: 'PENDING',
  page: '1',
  pageSize: '20'
});

const response = await fetch(
  `https://api.harmony.compago.com/api/one-time-payment?${params}`,
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);

const data = await response.json();
// Display data.items in your dashboard UI
```

### Reconciliation

Export all confirmed payments for a specific period:

```javascript theme={null}
// Fetch all confirmed payments for reconciliation
let allConfirmedPayments = [];
let page = 1;

while (true) {
  const params = new URLSearchParams({
    status: 'CONFIRMED',
    page: page.toString(),
    pageSize: '500' // Maximum page size for efficiency
  });

  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );

  const data = await response.json();
  allConfirmedPayments = allConfirmedPayments.concat(data.items);

  if (page * 500 >= data.count) break;
  page++;
}

// Export to CSV or process for reconciliation
```

### Reporting

Generate payment statistics:

```javascript theme={null}
// Fetch counts by status
const statuses = ['PENDING', 'CONFIRMED', 'CANCELLED'];
const stats = {};

for (const status of statuses) {
  const params = new URLSearchParams({
    status,
    page: '1',
    pageSize: '1' // We only need the count, not the items
  });

  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment?${params}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );

  const data = await response.json();
  stats[status] = data.count;
}

console.log('Payment Statistics:', stats);
// { PENDING: 42, CONFIRMED: 158, CANCELLED: 15 }
```

## Error Responses

<ResponseField name="400" type="error">
  Invalid request parameters or missing organization context.
</ResponseField>

<ResponseField name="401" type="error">
  Unauthorized - missing or invalid API key.
</ResponseField>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Payment" icon="plus" href="/one-time-payment/create">
    Learn how to create new one-time payment links
  </Card>

  <Card title="Cancel Payment" icon="xmark" href="/one-time-payment/cancel">
    Learn how to cancel active payment links
  </Card>
</CardGroup>