# Disconnect a processor connection

> The processor_connections.disconnect operation: POST /api/v1/processor_connections/{id}/disconnect in the REST API and the processor_connections_disconnect tool in the MCP server.

Disconnects a processor connection: its stored API key is destroyed and it can't take or refund payments any
more. Brands that use it as their primary or secondary connection must be assigned another one first
(`processor_connection_in_use`). Webhook events the processor still sends for earlier payments are recorded.
Delete the webhook endpoint in the processor's dashboard if you don't want them. To use the account again,
connect it again with `processor_connections.create`.

Needs a sign-in within the last 15 minutes in the console; security tier for agents. Dry-run it to see the
result first.

## At a glance

- **REST:** `POST /api/v1/processor_connections/{id}/disconnect`
- **MCP tool:** `processor_connections_disconnect`
- **Operation ID:** `processor_connections.disconnect`
- **Scope:** Legal entity
- **Permission:** `processors:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `processors:admin` scope
- **Fresh sign-in:** In the console, a sign-in within the last 15 minutes
- **Since:** M4

## Request

### Path parameters

| Field | Type        | Description |
| ----- | ----------- | ----------- |
| `id`  | `pcon_…` ID |             |

### Body

This operation takes no body.

## Response

`200 OK` with a JSON object:

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

## Examples

### Disconnect a connection no brand uses

```http
POST /api/v1/processor_connections/pcon_01m4vyt4mxe0s9zzk90373z6p6/disconnect
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
```

Response (`200`):

```json
{
  "id": "pcon_01m4vyt4mxe0s9zzk90373z6p6",
  "object": "processor_connection",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "livemode": false,
  "processor": "stripe",
  "label": "Stripe",
  "status": "disconnected",
  "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": "2026-10-14T12:05:00.000Z",
  "createdAt": "2026-10-14T12:00:00.000Z",
  "updatedAt": "2026-10-14T12:05:00.000Z",
  "version": 2
}
```

## Errors

| Code                                                                                                       | HTTP status | When                                                           | What to do                                                                                                                                         |
| ---------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                   | 404         | No such connection for this entity in this mode.               | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`processor_connection_in_use`](https://ownrecord.io/docs/reference/errors.md#processor_connection_in_use) | 409         | A brand uses it as primary or secondary (`details.brand_ids`). | Assign another connection to the brands listed in `details.brand_ids` first.                                                                       |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                       | 409         | The connection changed meanwhile; try again.                   | Fetch the object again and retry the change.                                                                                                       |
| [`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 manage processor connections here.                   | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |
| [`fresh_auth_required`](https://ownrecord.io/docs/reference/errors.md#fresh_auth_required)                 | 403         | Your last sign-in is older than 15 minutes.                    | Sign in again, then repeat the action within 15 minutes.                                                                                           |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).