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:

On update, each key is merged independently: pass an empty array or omit card_brands to clear the brand override, and pass installments_enabled: null to return it to unset.

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.

When Tokeflow takes a payment provider out of service, its connectors can still be renamed, have their credentials rotated, and be turned off — but a connector that is off cannot be turned back on (400) while the provider is inactive.

Refused credentials

If a provider starts refusing a connector's API credentials — a key that was revoked, rotated or restricted on the provider's side — Tokeflow confirms the refusal against the provider before acting on it. Once confirmed, subscription renewals routed to that connector are put on a billing hold instead of being declined and dunned. Save new credentials with PATCH and the hold is released; changing only the webhook_secret does not release 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 exactly the fields your provider requires — unknown keys are refused, and Tokeflow encrypts the values at rest and never returns them in full. The key's environment must match is_test_mode: a live key on a test-mode connector (or the reverse) is rejected before anything is stored. The provider slugs and their exact credential requirements are listed for your enabled providers in the Tokeflow Dashboard.

Provider-specific credentials

The exact credentials fields, the webhook_secret format and any extra payer data a provider needs are shown for your enabled providers in the Tokeflow Dashboard, and the Tokeflow team can confirm them for a provider you are about to enable. Three patterns cover the catalog:

Whatever the pattern, register the connector's webhook_url in the provider's own dashboard, and send payer_ip and a complete customer on card charges for providers that require them — see Supported providers.

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",
  "payment_provider_id": "pp_1a2b3c",
  "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",
      "payment_provider_id": "pp_1a2b3c",
      "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",
  "payment_provider_id": "pp_1a2b3c",
  "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",
  "payment_provider_id": "pp_1a2b3c",
  "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.