Connectors

A connector is one configured credential set for one payment service provider (PSP). Connecting the same provider twice — say, a test-mode and a live-mode credential set, or one account per country — produces two independent connectors. Everything downstream of setup speaks in connectors, not providers: routing profiles reference connectors, and every attempt in a transaction's timeline records the connector_id it ran through.

Tokeflow orchestrates charges across your connectors; it does not process or settle funds. The connector is where you hand Tokeflow the provider credentials it needs to submit charges on your behalf — and where you wire up the provider's webhooks so asynchronous events (PIX confirmations, chargebacks, refund updates) flow back in.

How a connector comes to life

Use GET /payment-providers to discover which providers are available to connect and the auth methods each one supports, create the connector, then point your routing at it.

The connector object

Connector config

config holds non-sensitive, per-connector overrides. It currently supports one:

On update, pass an empty array or omit card_brands to clear the override and fall back to the PSP default.

Active and inactive connectors

An inactive connector (is_active: false) is skipped by routing evaluation and is rejected as a routing profile's default connector by PATCH /routing/profiles/:id/default-connector. Deactivating is the safe way to take a credential set out of rotation without deleting it.

Endpoints

All connector endpoints are scoped under the merchant path. With an Organization key, merchant_id selects the target merchant; with a Merchant key, it must be the key's own merchant.

POST/api/v1/merchants/:merchant_id/connectors

Registers a PSP credential set for the merchant. Credentials are validated against the provider and stored encrypted. Use GET /payment-providers to list the providers available to connect and the auth methods each one supports.

Request fields

The credentials object

The shape of credentials depends on the connected provider. Some providers take a single API key; others take an access token plus a country, or an OAuth client_id/client_secret pair. Send the fields your provider requires — Tokeflow encrypts them at rest and never returns them in full. The provider slugs and their exact credential requirements are listed for your enabled providers in the Tokeflow Dashboard.

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_slug": "provider_a",
    "name": "Provider A BRL",
    "country_code": "BR",
    "is_test_mode": false,
    "auth_method": "api_key",
    "credentials": { "api_key": "sk_live_provider_key" },
    "webhook_secret": "whsec_9c41f2ab…",
    "config": { "card_brands": ["visa", "mastercard"] }
  }'

Example response — 201 Created

{
  "id": "conn_9f2b71",
  "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": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

Handle webhook_url as a secret

The returned webhook_url authenticates the provider's callbacks with a token embedded in its query string. Anyone holding that URL can post events to your connector, so give it the same handling as an API key:

• Paste it only into the provider's own webhook configuration, over HTTPS.
• Never put it in a ticket, a chat message, a screenshot, a log line, or a client-side bundle.
• If it leaks, rotate it by re-registering the connector, then update the URL in the provider's dashboard.

GET/api/v1/merchants/:merchant_id/connectors

Returns a paginated list of the merchant's payment provider connectors.

Query parameters

Example request

curl -G https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors \
  -H "Authorization: Bearer sk_live_org_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Example response — 200 OK

{
  "data": [
    {
      "id": "conn_9f2b71",
      "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": "2026-01-15T12:30:00Z",
      "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
      "has_webhook_secret": true,
      "config": { "card_brands": ["visa", "mastercard"] }
    },
    {
      "id": "conn_4d8ea0",
      "merchant_id": "mrc_123",
      "provider_slug": "provider_b",
      "name": "Provider B sandbox",
      "country_code": "BR",
      "auth_method": "api_key",
      "is_test_mode": true,
      "is_active": true,
      "created_at": "2026-01-10T09:15:00Z",
      "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_4d8ea0?token=whsec_…",
      "has_webhook_secret": true,
      "config": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

GET/api/v1/merchants/:merchant_id/connectors/:connector_id

Retrieves a single connector. Returns the connector object.

Example request

curl https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_9f2b71 \
  -H "Authorization: Bearer sk_live_org_…"

Example response — 200 OK

{
  "id": "conn_9f2b71",
  "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": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

A 404 (not_found_error) is returned if the connector does not exist or does not belong to the merchant.

PATCH/api/v1/merchants/:merchant_id/connectors/:connector_id

Partially updates a connector — credentials, label, or enabled state. Only the fields below can be changed; all are optional.

Request fields

Example request — rotate credentials and rename

curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_9f2b71 \
  -H "Authorization: Bearer sk_live_org_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Provider A BRL prod",
    "credentials": { "api_key": "sk_live_provider_key_rotated" }
  }'

Example response — 200 OK

{
  "id": "conn_9f2b71",
  "merchant_id": "mrc_123",
  "provider_slug": "provider_a",
  "name": "Provider A BRL prod",
  "country_code": "BR",
  "auth_method": "api_key",
  "is_test_mode": false,
  "is_active": true,
  "created_at": "2026-01-15T12:30:00Z",
  "webhook_url": "https://api.tokeflow.com/webhooks/connectors/conn_9f2b71?token=whsec_…",
  "has_webhook_secret": true,
  "config": { "card_brands": ["visa", "mastercard"] }
}

A 404 (not_found_error) is returned if the connector does not exist or does not belong to the merchant.

DELETE/api/v1/merchants/:merchant_id/connectors/:connector_id

Removes the connector. It must not be referenced by any routing node or be a routing profile's default connector — repoint those first.

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_123/connectors/conn_4d8ea0 \
  -H "Authorization: Bearer sk_live_org_…"

Response codes

Errors

Every error uses the standard envelope. The most common cases for this resource:

See Errors for the full envelope and type catalog.

Related

• Payment providers — discover connectable providers and their supported auth methods.
• Routing profiles — decide which connector handles each charge.
• Transactions — see connectors at work in the routing timeline.
• Authentication — provision keys and scopes.