Organization connectors

View and manage payment-provider connectors across the organization's merchants from the Dashboard.

These endpoints give the organization a cross-merchant view of connectors — each merchant's connection to a payment provider. From here an org admin can review coverage and manage connectors without switching merchant by merchant.

A connector still belongs to exactly one merchant; the organization view simply aggregates them. Disabling one takes it out of that merchant's routing immediately.

These endpoints power the Tokeflow Dashboard UI at the organization level. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-organization-id header, and the signed-in user must be a member of that organization.

The connector object

Returned by the list and retrieve endpoints on this page.

Field	Type	Description
`id`	string	Connector ID.
`merchant_id`	string	Merchant ID.
`provider_slug`	string	Payment provider slug.
`name`	string	Connector name.
`country_code`	string \| null	ISO 3166-1 alpha-2 country code.
`auth_method`	string	Authentication method (api_key for V1).
`is_test_mode`	boolean	Whether this is a test mode connector.
`is_active`	boolean	Whether the connector is active.
`created_at`	string	Connector creation timestamp. (ISO 8601 UTC).
`webhook_url`	string \| null	Webhook URL for receiving PSP events. Configure this in your PSP dashboard.
`has_webhook_secret`	boolean	Whether a webhook signing secret is configured.
`config`	object \| null	Optional non-sensitive per-connector config (e.g. card_brands override). Null when no overrides are set, in which case the SDK falls back to the PSP's default_supported_card_brands.

Endpoints

GET`/api/v1/org/connectors`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

List connectors for merchant.

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.

Example request

curl -G https://api.tokeflow.com/api/v1/org/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Example response — 200

{
  "data": [
    {
      "id": "conn_123abc...",
      "merchant_id": "mrc_123",
      "provider_slug": "provider_a",
      "name": "Provider A BRL",
      "country_code": "BR",
      "auth_method": "api_key",
      "is_test_mode": false,
      "is_active": true,
      "created_at": "2025-11-20T10:00:00Z",
      "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
      "has_webhook_secret": true,
      "config": {
        "card_brands": [
          "visa",
          "mastercard",
          "elo"
        ],
        "installments_enabled": true
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/connectors`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Create a new connector.

Request fields

Field	Type	Required	Description
`provider_slug`	string	Yes	Payment provider slug. One of `provider_a`, `provider_b`, `provider_c`, `checkout`, `provider_d`.
`name`	string	Yes	Connector name.
`country_code`	string	No	ISO 3166-1 alpha-2 country code. Nullable for non-country-specific PSPs.
`is_test_mode`	boolean	Yes	Whether this connector is in test mode.
`is_active`	boolean	No	Whether the connector is active on creation. Defaults to true when omitted. An inactive connector is skipped by routing evaluation and is rejected by PATCH /routing/profiles/:id/default-connector. Note that createRoutingProfile and updateRoutingProfile do not currently filter on is_active, so a profile can still be created with an inactive default — charges on it then fail at resolution time.
`credentials`	object	Yes	Provider-specific credentials for the connected provider — for example an API key, or an access token plus country. The exact fields depend on the provider. Values are encrypted at rest and never returned in full.
`webhook_secret`	string	No	PSP webhook signing secret for verifying inbound webhooks. Format depends on the provider: Provider A uses `whsec_...`; Provider B expects a stringified JSON object `{"username":"...","password":"..."}` used for HTTP Basic Auth verification.
`config`	object	No	Optional non-sensitive per-connector config. Currently supports a card_brands override that narrows the brands surfaced to the SDK.
`auth_method`	string	Yes	One of `api_key`, `oauth2`.

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_slug": "provider_a",
    "name": "Main Payment Processor",
    "country_code": "BR",
    "is_test_mode": false,
    "is_active": true,
    "credentials": {
      "api_key": "sk_test_123456789"
    },
    "webhook_secret": "whsec_abc123...",
    "config": {
      "card_brands": [
        "visa",
        "mastercard",
        "elo"
      ],
      "installments_enabled": true
    },
    "auth_method": "api_key"
  }'

Example response — 201

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

DELETE`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Delete a connector.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 204 No Content

An empty body is returned on success.

GET`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get connector by ID.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Example response — 200

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

PATCH`/api/v1/org/connectors/:connector_id`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Update a connector.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Request fields

Field	Type	Required	Description
`name`	string	No	Connector name.
`is_active`	boolean	No	Whether the connector is active.
`credentials`	object	No	Provider-specific credentials for the connected provider — for example an API key, or an access token plus country. The exact fields depend on the provider. Values are encrypted at rest and never returned in full.
`webhook_secret`	string	No	PSP webhook signing secret for verifying inbound webhooks. Format depends on the provider: Provider A uses `whsec_...`; Provider B expects a stringified JSON object `{"username":"...","password":"..."}` used for HTTP Basic Auth verification.
`config`	object	No	Optional non-sensitive per-connector config. Currently supports a card_brands override. Pass an empty array or omit card_brands to clear the override and fall back to the PSP default.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider A BRL Prod",
    "is_active": false,
    "credentials": {
      "api_key": "sk_live_stripe_new",
      "account_id": "acct_456"
    },
    "webhook_secret": "whsec_abc123...",
    "config": {
      "card_brands": [
        "visa",
        "mastercard",
        "elo"
      ],
      "installments_enabled": true
    }
  }'

Example response — 200

{
  "id": "conn_123abc...",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2025-11-20T10:00:00Z",
  "webhook_url": "https://api.example.com/webhooks/connectors/conn_123?token=whsec_abc123",
  "has_webhook_secret": true,
  "config": {
    "card_brands": [
      "visa",
      "mastercard",
      "elo"
    ],
    "installments_enabled": true
  }
}

POST`/api/v1/org/connectors/:connector_id/test`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Test connector credentials against the PSP.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

GET`/api/v1/org/connectors/:connector_id/webhooks/inbounds`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get inbound webhook events for a connector.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.
`status`	string	No	Filter by webhook event status
`from`	string	No	Inclusive lower bound for received_at (ISO 8601)
`to`	string	No	Inclusive upper bound for received_at (ISO 8601)

Example request

curl -G https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/webhooks/inbounds \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=pending" \
  --data-urlencode "from=2026-04-01T00:00:00Z"

GET`/api/v1/org/connectors/:connector_id/webhooks/invalid`

Org

Auth: Dashboard session (JWT bearer). Organization membership required.

Get invalid webhook events for a connector.

Path parameters

Field	Type	Required	Description
`connector_id`	string	Yes	—

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.
`from`	string	No	Inclusive lower bound for received_at (ISO 8601)
`to`	string	No	Inclusive upper bound for received_at (ISO 8601)

Example request

curl -G https://api.tokeflow.com/api/v1/org/connectors/conn_a1b2c3d4/webhooks/invalid \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "from=2026-04-01T00:00:00Z" \
  --data-urlencode "to=2026-04-30T23:59:59Z"

Errors

Errors use the standard envelope. The most common cases here:

HTTP	Meaning
`400`	Invalid parameters or a state that does not allow this operation.
`401`	Missing, expired, or invalid Dashboard session token.
`403`	Authenticated, but the signed-in user lacks access to this entity.
`404`	The record does not exist or is not visible to this entity.

Organization connectors

The connector object

Endpoints

GET/api/v1/org/connectors

POST/api/v1/org/connectors

DELETE/api/v1/org/connectors/:connector_id

GET/api/v1/org/connectors/:connector_id

PATCH/api/v1/org/connectors/:connector_id

POST/api/v1/org/connectors/:connector_id/test

GET/api/v1/org/connectors/:connector_id/webhooks/inbounds

GET/api/v1/org/connectors/:connector_id/webhooks/invalid

Errors

Related

On this page

GET`/api/v1/org/connectors`

POST`/api/v1/org/connectors`

DELETE`/api/v1/org/connectors/:connector_id`

GET`/api/v1/org/connectors/:connector_id`

PATCH`/api/v1/org/connectors/:connector_id`

POST`/api/v1/org/connectors/:connector_id/test`

GET`/api/v1/org/connectors/:connector_id/webhooks/inbounds`

GET`/api/v1/org/connectors/:connector_id/webhooks/invalid`