---
title: "List the payment connections of a NIF"
method: GET
path: "/v1/companies/{company_id}/payment-connections"
tags: ["CompanyPaymentConnections"]
---

# List the payment connections of a NIF

`GET /v1/companies/{company_id}/payment-connections`

## Request

- Base URL: `https://app.beel.es/api`
- URL: `https://app.beel.es/api/v1/companies/{company_id}/payment-connections`
- Auth: HTTP bearer

Returns the payment provider connections of a company your account **owns or
manages**, with the provider-side account each one points at and its `status`. Use it to
check whether a NIF you provisioned has completed its connection.

- **A NIF with no connections:** answers `200` with an empty list.
- **`environment`:** Test and Live connections are independent, so only the ones living in
  the mode of the key you ask with are returned; this field states which.

**Closed catalogue.** A NIF is not limited to one connection per provider: within a single
environment it may hold several of the same provider, one per external account. What is
unique is the external account itself — one live connection per provider, environment and
external account. The set is still bounded and unpaginated: the collection carries no
`pagination` and takes no `page`/`limit`, and every response holds the whole set for the
environment of the key you ask with.

## Response `200`

Connections of the NIF

- ListManagedPaymentConnectionsResponse
  - `success` boolean
  - `data` object
    - `connections` ManagedPaymentConnection[], required
      - `id` string, uuid, required: Unique identifier of the connection. It is what addresses the connection everywhere else — `PATCH`, `DELETE` and events all take it as `{connection_id}`.
      - `provider` string, required: Payment provider slug (lowercase).
      - `external_account_id` string, required: Provider-side account id (e.g. Stripe `acct_...`).
      - `external_account_name` string, nullable: Provider-side account display name, if any.
      - `environment` 'TEST' | 'PROD', required: Mode a record lives in — its Test/Live twin. It decides where invoices, customers and quota are accounted. For a company it also decides which AEAT its NIF is registered against: switching a company on in `PROD` is what registers it with the real AEAT, so `aeat_environment` is that same mode and uses this same enum.
      - `status` 'PENDING' | 'ACTIVE' | 'DISCONNECTED' | 'ERROR', required: Status of the payment provider connection. - `PENDING`: authorization opened, not completed yet - `ACTIVE`: the connection invoices incoming charges - `DISCONNECTED`: withdrawn — it no longer invoices anything - `ERROR`: the provider rejected the last call, so it needs reconnecting
      - `connected_at` string, date-time, nullable: When the connection was established.
  - `meta` ResponseMeta
    - `timestamp` string, date-time
    - `request_id` string

## Other responses

- `400`: The request target could not be read as declared, so nothing was looked up. Three causes, all named in `error.details`: a path or query parameter whose value does not parse as its type (`VALIDATION_ERROR` — a UUID that is not a UUID, an unknown enum value, an empty element in a list such as `status=ISSUED,`), a required parameter that was not sent (`MISSING_PARAMETER`), or a header that is meant to carry an identifier and does not (`ACTIVE_COMPANY_HEADER_INVALID`). A list parameter sent entirely empty (`status=`) is not an error: it is the same as omitting it. The fault is in the target, not in the content — which is what `422` is defined over.
- `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those.
- `403`: Your account does not own or manage this company. The same answer is given for a NIF that does not exist. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`.
- `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known.
- `500`: Internal server error
- `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry.

---

[API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)