# List processor connections

> The processor_connections.list operation: GET /api/v1/processor_connections in the REST API and the processor_connections_list tool in the MCP server.

Lists the legal entity's processor connections in the mode of the request, newest first: processor, label,
status, the key hint (never the key), the webhook endpoint and when the last event arrived, and the last
connection test. Filter by `processor` and `status`; paginate with `limit` (1–100, default 10) and
`starting_after`.

## At a glance

- **REST:** `GET /api/v1/processor_connections`
- **MCP tool:** `processor_connections_list`
- **Operation ID:** `processor_connections.list`
- **Scope:** Legal entity
- **Permission:** `processors:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `processors:read` scope
- **Since:** M4

## Request

### Query parameters

| Field            | Type                                        | Required | Description |
| ---------------- | ------------------------------------------- | -------- | ----------- |
| `limit`          | integer (1 to 100)                          | No       |             |
| `starting_after` | `pcon_…` ID                                 | No       |             |
| `processor`      | one of `stripe`, `mollie`, `fake`           | No       |             |
| `status`         | one of `active`, `degraded`, `disconnected` | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                                | Type                                                | Description |
| ------------------------------------ | --------------------------------------------------- | ----------- |
| `object`                             | `"list"`                                            |             |
| `data`                               | array of object                                     |             |
| `data[].id`                          | `pcon_…` ID                                         |             |
| `data[].object`                      | `"processor_connection"`                            |             |
| `data[].entityId`                    | `ent_…` ID                                          |             |
| `data[].livemode`                    | boolean                                             |             |
| `data[].processor`                   | one of `stripe`, `mollie`, `fake`                   |             |
| `data[].label`                       | string                                              |             |
| `data[].status`                      | one of `active`, `degraded`, `disconnected`         |             |
| `data[].statusReason`                | string or null                                      |             |
| `data[].accountId`                   | string or null                                      |             |
| `data[].keyHint`                     | string                                              |             |
| `data[].publishableKey`              | string or null                                      |             |
| `data[].checkoutComponent`           | one of `stripe_payment_element`, `redirect`, `fake` |             |
| `data[].webhook`                     | object                                              |             |
| `data[].webhook.mode`                | one of `managed`, `manual`                          |             |
| `data[].webhook.url`                 | string                                              |             |
| `data[].webhook.endpointId`          | string or null                                      |             |
| `data[].webhook.lastEventAt`         | date-time or null                                   |             |
| `data[].lastTest`                    | object                                              |             |
| `data[].lastTest.ok`                 | boolean                                             |             |
| `data[].lastTest.missingPermissions` | array of string                                     |             |
| `data[].lastTest.message`            | string or null                                      |             |
| `data[].lastTest.checkedAt`          | date-time                                           |             |
| `data[].failures`                    | object or null                                      |             |
| `data[].disconnectedAt`              | date-time or null                                   |             |
| `data[].createdAt`                   | date-time                                           |             |
| `data[].updatedAt`                   | date-time                                           |             |
| `data[].version`                     | integer (at least 1)                                |             |
| `has_more`                           | boolean                                             |             |
| `next_cursor`                        | `pcon_…` ID or null                                 |             |

## Examples

### The entity's connections

```http
GET /api/v1/processor_connections
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "pcon_01m4vyt4mxe0s9zzk90373z6p7",
      "object": "processor_connection",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "livemode": false,
      "processor": "fake",
      "label": "Fake processor",
      "status": "active",
      "statusReason": null,
      "accountId": "acct_fake_0123456789abcdef",
      "keyHint": "fake_…9f2c",
      "publishableKey": null,
      "checkoutComponent": "fake",
      "webhook": {
        "mode": "managed",
        "url": "http://localhost:3000/api/webhooks/fake/pcon_01m4vyt4mxe0s9zzk90373z6p7",
        "endpointId": "we_fake_0123456789abcdef01234567",
        "lastEventAt": null
      },
      "lastTest": {
        "ok": true,
        "missingPermissions": [],
        "message": null,
        "checkedAt": "2026-10-14T12:00:00.000Z"
      },
      "failures": null,
      "disconnectedAt": null,
      "createdAt": "2026-10-14T12:00:00.000Z",
      "updatedAt": "2026-10-14T12:00:00.000Z",
      "version": 1
    },
    {
      "id": "pcon_01m4vyt4mxe0s9zzk90373z6p6",
      "object": "processor_connection",
      "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
      "livemode": false,
      "processor": "stripe",
      "label": "Stripe",
      "status": "active",
      "statusReason": null,
      "accountId": "acct_1ExampleAccount01",
      "keyHint": "rk_test_…AbCd",
      "publishableKey": "pk_test_ExampleOnlyNotARealKey000000000AbCd",
      "checkoutComponent": "stripe_payment_element",
      "webhook": {
        "mode": "managed",
        "url": "https://ownrecord.io/api/webhooks/stripe/pcon_01m4vyt4mxe0s9zzk90373z6p6",
        "endpointId": "we_1ExampleEndpoint01",
        "lastEventAt": null
      },
      "lastTest": {
        "ok": true,
        "missingPermissions": [],
        "message": null,
        "checkedAt": "2026-10-14T12:00:00.000Z"
      },
      "failures": null,
      "disconnectedAt": null,
      "createdAt": "2026-10-14T12:00:00.000Z",
      "updatedAt": "2026-10-14T12:00:00.000Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                      | What to do                                                                                                                                         |
| -------------------------------------------------------------------------------------- | ----------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or pagination value is invalid.  | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)       | 400         | The request names no legal entity.        | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't see processor connections here. | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).