Docs

Billpay · API reference

List Payees

GET /api/v1/payees
Try it ▸

Base URL not set in the spec · operationId listPayees

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.

Authorization

BearerAuth Bearer token

Query parameters

page integer

Page number (starts at 1).

Example 1
Default 1
name string

Case-insensitive partial match on the payee display name.

Example Movistar
category string

Exact match on payee industry/category.

Example Telecommunications
Telecommunications Telephone Cable Internet Gas Water Electricity Bank Beauty Unknown Government Transportation Retail Giftcard
connection_mode string

Filter by integration connection mode.

Example online
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).

Example false

Responses

200 Payee list retrieved successfully. application/json
meta object required

Pagination metadata for list responses.

current_page meta.current_page integer required

Current page number.

next_page meta.next_page integer | null required

Next page number, or null if this is the last page.

prev_page meta.prev_page integer | null required

Previous page number, or null if this is the first page.

total_pages meta.total_pages integer required

Total number of pages for the current filters.

total_count meta.total_count integer required

Total number of payees matching the current filters.

payees array of Payee required
payee_id payees[].payee_id string (uuid) required

Unique payee identifier.

name payees[].name string required

Display name of the payee.

category payees[].category string required

Industry or category label for the payee.

type payees[].type string required

Payee category for integration behavior (e.g. Bill, Topup).

reference_config payees[].reference_config object required

Optional hints for validating the payer reference or account number format.

regex payees[].reference_config.regex string | null required

Regular expression pattern used to validate references, when available.

financial_rules payees[].financial_rules object

Payment amount constraints and billing rules. Typically present when type is Bill; may be omitted for other payee types.

minimum_amount payees[].financial_rules.minimum_amount string required

Minimum payment amount (decimal string in currency units).

maximum_amount payees[].financial_rules.maximum_amount string required

Maximum payment amount (decimal string in currency units).

payment_type payees[].financial_rules.payment_type string required

Supported payment mode for this payee.

totals partials
accepts_expired payees[].financial_rules.accepts_expired boolean required

Whether payments are accepted when the bill is expired.

capabilities payees[].capabilities object

Operational capabilities. Typically present when type is Bill; may be omitted for other payee types.

has_balance payees[].capabilities.has_balance boolean required

Whether a balance inquiry can be performed for this payee.

connection_mode payees[].capabilities.connection_mode string required

How the payee integration is executed.

online batch
currency payees[].currency string | null

Currency for the payee. Typically present when category is Giftcard.

images payees[].images object | null

Product images. Typically present when category is Giftcard.

small payees[].images.small object
id payees[].images.small.id string
url payees[].images.small.url string
large payees[].images.large object
id payees[].images.large.id string
url payees[].images.large.url string
redemption_info payees[].redemption_info string | null

Instructions or info for redeeming the gift card. Typically present when type is EGift.

price payees[].price string | null

Fixed price of the gift card. Typically present when type is EGift.

bundles payees[].bundles array of (string | number) | null

Predefined top-up amounts. Typically present when type is Topup. Values follow the format returned by the API (string or numeric).

401 Unauthorized application/json
errors array of string required
This request is in the Monato · Billpay Postman collection.Download collection

Request

curl -X GET "$BASE_URL/api/v1/payees" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 3,
    "total_count": 45
  },
  "payees": [
    {
      "payee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "AVON",
      "category": "Beauty",
      "type": "Bill",
      "reference_config": {
        "regex": "^[0-9]{20}$"
      },
      "financial_rules": {
        "minimum_amount": "0",
        "maximum_amount": "8000",
        "payment_type": "totals",
        "accepts_expired": true
      },
      "capabilities": {
        "has_balance": false,
        "connection_mode": "online"
      }
    },
    {
      "payee_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "CFE",
      "category": "Electricity",
      "type": "Bill",
      "reference_config": {
        "regex": "^[0-9]{10,12}$"
      },
      "financial_rules": {
        "minimum_amount": "1",
        "maximum_amount": "50000",
        "payment_type": "totals",
        "accepts_expired": false
      },
      "capabilities": {
        "has_balance": true,
        "connection_mode": "batch"
      }
    }
  ]
}