Test a processor connection

Tests a connection's stored key at the processor: is it still accepted, for which account and mode, and which permissions a restricted key lacks. The result is stored on the connection (lastTest) and returned; a failed test isn't an error. The connection's status doesn't change (mark it degraded with processor_connections.update to send new checkouts to the brand's secondary connection).

A dry run returns a simulated test without calling the processor or storing anything.

At a glance

REST: POST /api/v1/processor_connections/{id}/test
MCP tool: processor_connections_test
Operation ID: processor_connections.test
Scope: Legal entity
Permission: processors:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the processors:write scope
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

A key that lost a permission

HTTP

POST /api/v1/processor_connections/pcon_01m4vyt4mxe0s9zzk90373z6p6/test
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": "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": false,
    "missingPermissions": ["refunds:write"],
    "message": "The key is missing a permission.",
    "checkedAt": "2026-10-14T12:05:00.000Z"
  },
  "failures": null,
  "disconnectedAt": null,
  "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`	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_disconnected`	409	The connection is disconnected (its key is gone).	Connect the processor again, or use another connection of the entity.
`processor_not_available`	400	A fake connection where development access is off.	Connect Stripe or Mollie. The fake processor exists only in development and test.
`processor_request_failed`	502	The processor couldn't be reached.	If `retryable` is true, retry with the same Idempotency-Key after a short wait; otherwise check `details.code`.
`upstream_timeout`	502	The processor didn't answer in time.	Retry the request with the same Idempotency-Key after a short wait.
`version_conflict`	409	The connection changed while it was being tested; test again.	Fetch the object again and retry the change.
`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`	403	You can't test 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: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

A key that lost a permission#

Errors#