# List Payees

Returns a paginated list of payees in alphabetical order by display name.

Optional query parameters filter the result set. When multiple filters are supplied,
all of them apply together (logical AND).

Filters

- name — Case-insensitive match anywhere in the payee display name (not prefix-only).
- category — Exact match on the payee industry/category.
- connection_mode — How the service is connected (online or batch).
- has_balance — Whether balance inquiry is supported for that payee.
- accepts_expired — Whether payments on expired bills are allowed for that payee.

Endpoint: GET /api/v1/payees
Version: 1.0.0
Security: BearerAuth

## Query parameters:

  - `page` (integer)
    Page number (starts at 1).
    Example: 1

  - `name` (string)
    Case-insensitive partial match on the payee display name.
    Example: "Movistar"

  - `category` (string)
    Exact match on payee industry/category.
    Enum: "Telecommunications", "Telephone", "Cable", "Internet", "Gas", "Water", "Electricity", "Bank", "Beauty", "Unknown", "Government", "Transportation", "Retail"

  - `connection_mode` (string)
    Filter by integration connection mode.
    Enum: "online", "batch"

  - `has_balance` (boolean)
    Filter payees that support balance inquiry (true) or that do not (false).
    Example: true

  - `accepts_expired` (boolean)
    Filter payees that allow payments on expired bills (true) or not (false).

## Response 200 fields (application/json):

  - `meta` (object, required)
    Pagination metadata for list responses.

  - `meta.current_page` (integer, required)
    Current page number.
    Example: 1

  - `meta.next_page` (integer,null, required)
    Next page number, or null if this is the last page.
    Example: 2

  - `meta.prev_page` (integer,null, required)
    Previous page number, or null if this is the first page.

  - `meta.total_pages` (integer, required)
    Total number of pages for the current filters.
    Example: 3

  - `meta.total_count` (integer, required)
    Total number of payees matching the current filters.
    Example: 45

  - `payees` (array, required)

  - `payees.payee_id` (string, required)
    Unique payee identifier.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `payees.name` (string, required)
    Display name of the payee.
    Example: "CFE"

  - `payees.category` (string, required)
    Industry or category label for the payee.
    Example: "Electricity"

  - `payees.type` (string, required)
    Payee category for integration behavior (e.g. Bill, Topup).
    Example: "Bill"

  - `payees.reference_config` (object, required)
    Optional hints for validating the payer reference or account number format.

  - `payees.reference_config.regex` (string,null, required)
    Regular expression pattern used to validate references, when available.
    Example: "^[0-9]{12}$"

  - `payees.financial_rules` (object)
    Payment amount constraints and billing rules. Typically present when type is Bill;
may be omitted for other payee types.

  - `payees.financial_rules.minimum_amount` (string, required)
    Minimum payment amount (decimal string in currency units).
    Example: "1"

  - `payees.financial_rules.maximum_amount` (string, required)
    Maximum payment amount (decimal string in currency units).
    Example: "50000"

  - `payees.financial_rules.payment_type` (string, required)
    Supported payment mode for this payee.
    Enum: "totals", "partials"

  - `payees.financial_rules.accepts_expired` (boolean, required)
    Whether payments are accepted when the bill is expired.

  - `payees.capabilities` (object)
    Operational capabilities. Typically present when type is Bill;
may be omitted for other payee types.

  - `payees.capabilities.has_balance` (boolean, required)
    Whether a balance inquiry can be performed for this payee.
    Example: true

  - `payees.capabilities.connection_mode` (string, required)
    How the payee integration is executed.
    Enum: "online", "batch"

  - `payees.bundles` (array,null)
    Predefined top-up amounts. Typically present when type is Topup.
Values follow the format returned by the API (string or numeric).
    Example: ["10.00","20.00","50.00"]

## Response 401 fields (application/json):

  - `errors` (array, required)
    Example: ["Access denied"]