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

> Query and filter payments across all your organizations.

The **List Payments** endpoint allows you to retrieve a paginated list of payments across all organizations managed by your sales partner account. It supports a wide range of filters for building custom reports, dashboards, and integrations.

## What You Can Do

With the List Payments endpoint, you can:

* **Query all payments** across every organization in your sales partner account
* **Filter by status** to track pending, confirmed, cancelled, or refunded payments
* **Filter by date range** to generate period-based reports
* **Filter by organization** to view payments for specific merchants
* **Search by text** to find payments by amount or organization name
* **Paginate results** using offset-based pagination for large datasets

## Use Cases

* **Reconciliation dashboards**: Pull payment data into your internal tools for reconciliation
* **Periodic reporting**: Generate daily, weekly, or monthly payment reports filtered by date range
* **Organization monitoring**: Track payment activity for specific organizations
* **Transaction lookup**: Find specific payments by ID or operation code

## Endpoint

```
GET /api/developer/payment
```

**API Reference:** [`GET /payment`](/sales-partner/api-reference/payment/list)

## Authentication

Include your API key in the request headers:

```
x-api-key: YOUR_API_KEY
```

## Query Parameters

| Parameter             | Type                 | Description                                                       |
| --------------------- | -------------------- | ----------------------------------------------------------------- |
| `id`                  | `string`             | Filter by a specific payment ID (UUID)                            |
| `status`              | `string \| string[]` | Filter by status: `PENDING`, `CANCELLED`, `CONFIRMED`, `REFUNDED` |
| `type`                | `string \| string[]` | Filter by type: `CARD_NOT_PRESENT`, `CARD_PRESENT`                |
| `financingMethod`     | `string \| string[]` | Filter by financing method: `INSTALLMENTS`, `PAY_NOW`             |
| `terms`               | `number \| number[]` | Filter by number of installment terms (e.g. 3, 6, 12)             |
| `issuingBank`         | `string \| string[]` | Filter by the card's issuing bank                                 |
| `organizationId`      | `string \| string[]` | Filter by organization ID (UUID)                                  |
| `createdAtFrom`       | `date`               | Filter payments created on or after this date                     |
| `createdAtTo`         | `date`               | Filter payments created on or before this date                    |
| `operationCodeSearch` | `string`             | Search by operation code (partial match)                          |
| `q`                   | `string`             | Free text search (matches amount and organization name)           |
| `limit`               | `number`             | Number of results per page (default: 20, max: 100)                |
| `offset`              | `number`             | Number of results to skip (default: 0)                            |

<Note>
  Array parameters are passed by repeating the parameter: `?status=PENDING&status=CONFIRMED`
</Note>

## Response Structure

The response contains a `data` array with payment objects and a `pagination` object:

### Payment Object

| Field                 | Type             | Description                                                                                |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `id`                  | `string`         | Unique payment identifier                                                                  |
| `status`              | `string`         | Payment status: `PENDING`, `CANCELLED`, `CONFIRMED`, `REFUNDED`                            |
| `type`                | `string`         | `CARD_NOT_PRESENT` or `CARD_PRESENT`                                                       |
| `financingMethod`     | `string`         | `INSTALLMENTS` or `PAY_NOW`                                                                |
| `operationCode`       | `number`         | Unique operation code                                                                      |
| `amount`              | `number`         | Payment amount                                                                             |
| `currency`            | `string`         | Currency code (e.g. `MXN`)                                                                 |
| `terms`               | `number`         | Number of installment terms                                                                |
| `periodicity`         | `string`         | Installment periodicity (e.g. `MONTHLY`)                                                   |
| `createdAt`           | `string`         | ISO 8601 timestamp                                                                         |
| `organization`        | `object`         | Organization `id` and `name`                                                               |
| `cardInformation`     | `object \| null` | Card details: `lastFourDigits`, `networkType`, `issuingBank`, `fundingSource`, `entryMode` |
| `paymentDisbursement` | `object \| null` | Fee breakdown and disbursement amounts                                                     |
| `transaction`         | `object \| null` | Bank reference and processor response                                                      |
| `terminal`            | `object \| null` | POS terminal details (only for card-present payments)                                      |
| `billingInformation`  | `object \| null` | Customer billing details captured at checkout                                              |
| `salesperson`         | `object \| null` | Salesperson who processed the payment (POS only)                                           |
| `businessStoreBranch` | `object \| null` | Store branch where the payment was processed (POS only)                                    |

### Payment Disbursement Object

The `paymentDisbursement` object contains the full fee breakdown:

| Field                               | Type     | Description                                     |
| ----------------------------------- | -------- | ----------------------------------------------- |
| `feePercentage`                     | `number` | Total fee percentage                            |
| `promotionFeeDiscount`              | `number` | Fee discount from promotions                    |
| `finalFeePercentageForMerchant`     | `number` | Effective merchant fee percentage               |
| `finalFeePercentageForManufacturer` | `number` | Effective manufacturer fee percentage           |
| `promotionBusinessTake`             | `number` | Manufacturer's promotion allocation percentage  |
| `feeAmount`                         | `string` | Total fee amount                                |
| `merchantFeeAmount`                 | `string` | Merchant's fee amount                           |
| `manufacturerFeeAmount`             | `string` | Manufacturer's fee amount                       |
| `merchantIvaFeeAmount`              | `string` | IVA on merchant's fee                           |
| `manufacturerIvaFeeAmount`          | `string` | IVA on manufacturer's fee                       |
| `totalFeeIva`                       | `string` | Total IVA (16%) on the total fee                |
| `promotionTakeAmount`               | `string` | Amount allocated to manufacturer from promotion |
| `merchantTakeAmount`                | `string` | Net amount the merchant receives                |
| `manufacturerTakeAmount`            | `string` | Net amount the manufacturer receives            |

### Card Information Object

The `cardInformation` object provides details about the card used for the payment:

| Field            | Type             | Description                                                             |
| ---------------- | ---------------- | ----------------------------------------------------------------------- |
| `lastFourDigits` | `string`         | Masked last four digits of the card number                              |
| `networkType`    | `string`         | Card network brand: `VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`, `UNKNOWN` |
| `issuingBank`    | `string \| null` | Name of the bank that issued the card                                   |
| `fundingSource`  | `string \| null` | Funding source: `DEBIT` or `CREDIT`                                     |
| `entryMode`      | `string \| null` | How the card was captured: `MAGNETIC`, `CHIP`, `CONTACTLESS`            |

### Transaction Object

The `transaction` object provides details about the payment transaction:

| Field             | Type             | Description                                     |
| ----------------- | ---------------- | ----------------------------------------------- |
| `bankReference`   | `string \| null` | Bank reference number                           |
| `rawResponseText` | `string \| null` | Response text from the payment processor        |
| `authResult`      | `string \| null` | Authorization result code                       |
| `createdAt`       | `string`         | ISO 8601 timestamp of the transaction           |
| `authCode`        | `string \| null` | Authorization code returned by the card network |
| `resultCode`      | `string \| null` | Processor result code for the transaction       |

### Terminal Object

The `terminal` object is populated for card-present payments and identifies the POS terminal used to capture the charge:

| Field          | Type     | Description                       |
| -------------- | -------- | --------------------------------- |
| `serialNumber` | `string` | Serial number of the POS terminal |

### Billing Information Object

The `billingInformation` object contains the customer details captured at checkout:

| Field         | Type             | Description                                                             |
| ------------- | ---------------- | ----------------------------------------------------------------------- |
| `email`       | `string`         | Customer email address                                                  |
| `firstName`   | `string`         | Customer first name                                                     |
| `lastName`    | `string`         | Customer last name                                                      |
| `phoneNumber` | `string`         | Customer phone number                                                   |
| `address`     | `object \| null` | Customer billing address with `addressLine`, `city`, `state`, and `zip` |

### Salesperson Object

The `salesperson` object identifies the salesperson who processed the payment on a POS device:

| Field      | Type     | Description                                             |
| ---------- | -------- | ------------------------------------------------------- |
| `id`       | `string` | Unique identifier of the salesperson                    |
| `name`     | `string` | Display name of the salesperson                         |
| `username` | `string` | Username used by the salesperson to sign in on POS apps |

### Business Store Branch Object

The `businessStoreBranch` object identifies the store branch where the payment was processed:

| Field  | Type     | Description                           |
| ------ | -------- | ------------------------------------- |
| `id`   | `string` | Unique identifier of the store branch |
| `name` | `string` | Display name of the store branch      |

## Examples

### Basic Request

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?limit=10"
```

### Filter by Status

```bash theme={null}
# Single status
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?status=CONFIRMED"

# Multiple statuses
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?status=PENDING&status=CONFIRMED"
```

### Filter by Date Range

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?createdAtFrom=2026-03-01&createdAtTo=2026-03-31"
```

### Filter by Organization

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?organizationId=11111111-2222-3333-4444-555555555555"
```

### Lookup by Payment ID

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
```

### Combined Filters with Pagination

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?status=CONFIRMED&type=CARD_NOT_PRESENT&terms=3&limit=20&offset=40"
```

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "CONFIRMED",
      "type": "CARD_NOT_PRESENT",
      "financingMethod": "INSTALLMENTS",
      "operationCode": 10000000001,
      "amount": 1500,
      "currency": "MXN",
      "terms": 6,
      "periodicity": "MONTHLY",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "organization": {
        "id": "11111111-2222-3333-4444-555555555555",
        "name": "Acme Store"
      },
      "cardInformation": {
        "lastFourDigits": "**89",
        "networkType": "VISA",
        "issuingBank": "Bank of Example",
        "fundingSource": "CREDIT",
        "entryMode": "CHIP"
      },
      "paymentDisbursement": {
        "feePercentage": 3.5,
        "promotionFeeDiscount": 0,
        "finalFeePercentageForMerchant": 3.5,
        "finalFeePercentageForManufacturer": 0,
        "promotionBusinessTake": 0,
        "feeAmount": "52.50",
        "merchantFeeAmount": "52.50",
        "manufacturerFeeAmount": "0.00",
        "merchantIvaFeeAmount": "8.40",
        "manufacturerIvaFeeAmount": "0.00",
        "totalFeeIva": "8.40",
        "promotionTakeAmount": "0.00",
        "merchantTakeAmount": "1439.10",
        "manufacturerTakeAmount": "0.00"
      },
      "transaction": {
        "bankReference": "123456789012",
        "rawResponseText": "Approved",
        "authResult": null,
        "createdAt": "2026-01-15T10:30:45.000Z",
        "authCode": "123456",
        "resultCode": "00"
      },
      "terminal": {
        "serialNumber": "TERM-00000001"
      },
      "billingInformation": {
        "email": "customer@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "phoneNumber": "+5215555555555",
        "address": {
          "addressLine": "Calle Example 123",
          "city": "Ciudad de Mexico",
          "state": "CDMX",
          "zip": "01000"
        }
      },
      "salesperson": {
        "id": "dddddddd-eeee-ffff-0000-111111111111",
        "name": "Maria Garcia",
        "username": "maria.garcia"
      },
      "businessStoreBranch": {
        "id": "eeeeeeee-ffff-0000-1111-222222222222",
        "name": "Polanco Branch"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 1
  }
}
```

## Pagination

The API uses offset-based pagination. Use `limit` and `offset` to navigate through results.

```bash theme={null}
# Page 1 (first 20 results)
?limit=20&offset=0

# Page 2 (results 21-40)
?limit=20&offset=20

# Page 3 (results 41-60)
?limit=20&offset=40
```

The `pagination.count` field in the response tells you how many results were returned in the current page. If `count` is less than `limit`, you have reached the last page.

## Important Notes

### Security Scope

All requests are automatically scoped to your sales partner account. You can only access payments belonging to organizations under your account, regardless of the filters you apply. The `organizationId` filter lets you narrow results further, but it cannot access organizations outside your scope.

### Date Filtering

Date range filters (`createdAtFrom`, `createdAtTo`) use Mexico City timezone (CST/CDT). The filter is inclusive: `createdAtFrom` matches from the start of the given day, and `createdAtTo` matches until the end of the given day.

## Error Handling

| Status Code | Description                | Solution                                                              |
| ----------- | -------------------------- | --------------------------------------------------------------------- |
| `400`       | Invalid query parameters   | Check enum values, UUID format, and date format                       |
| `401`       | Missing or invalid API key | Verify your API key is correct and included in the `x-api-key` header |

### Example Validation Error

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.honor.compago.com/api/developer/payment?status=INVALID"
```

```json theme={null}
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_enum_value",
        "options": ["PENDING", "CANCELLED", "CONFIRMED", "REFUNDED"],
        "path": ["status"],
        "message": "Invalid enum value"
      }
    ]
  }
}
```