Merchant connectors

Manage a merchant's payment-provider connections from the Dashboard — add credentials, toggle a connector on or off, and remove one.

A connector is one merchant's connection to a payment provider: the credentials, the environment it points at, and whether it is currently enabled. These endpoints back the Dashboard's connectors screen.

Connectors are what routing rules point at — a routing profile can only send a charge to a provider this merchant has a connector for. Disabling a connector takes it out of routing immediately, so charges that would have gone to it cascade to the next eligible option instead.

These endpoints power the Tokeflow Dashboard UI. 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-merchant-id header identifying the merchant in context, and the signed-in user must be a member with access to it.

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/merchant/connectors`

Merchant

Auth: Dashboard session (JWT bearer). Merchant 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/merchant/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

POST`/api/v1/merchant/connectors`

Merchant

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

Create 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/merchant/connectors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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/merchant/connectors/:id`

Merchant

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

Delete connector.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET`/api/v1/merchant/connectors/:id`

Merchant

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

Get connector by ID.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

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/merchant/connectors/:id`

Merchant

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

Update connector.

Path parameters

Field	Type	Required	Description
`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/merchant/connectors/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -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/merchant/connectors/:id/test`

Merchant

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

Test connector credentials against the PSP.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchant/connectors/obj_1a2b3c4d/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

GET`/api/v1/merchant/connectors/:id/webhooks/inbounds`

Merchant

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

Get inbound webhooks for a connector.

Path parameters

Field	Type	Required	Description
`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/merchant/connectors/obj_1a2b3c4d/webhooks/inbounds \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=pending" \
  --data-urlencode "from=2026-04-01T00:00:00Z"

GET`/api/v1/merchant/connectors/:id/webhooks/invalid`

Merchant

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

Get invalid webhook events for a connector.

Path parameters

Field	Type	Required	Description
`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/merchant/connectors/obj_1a2b3c4d/webhooks/invalid \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --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.

Merchant connectors

The connector object

Endpoints

GET/api/v1/merchant/connectors

POST/api/v1/merchant/connectors

DELETE/api/v1/merchant/connectors/:id

GET/api/v1/merchant/connectors/:id

PATCH/api/v1/merchant/connectors/:id

POST/api/v1/merchant/connectors/:id/test

GET/api/v1/merchant/connectors/:id/webhooks/inbounds

GET/api/v1/merchant/connectors/:id/webhooks/invalid

Errors

Related

On this page

GET`/api/v1/merchant/connectors`

POST`/api/v1/merchant/connectors`

DELETE`/api/v1/merchant/connectors/:id`

GET`/api/v1/merchant/connectors/:id`

PATCH`/api/v1/merchant/connectors/:id`

POST`/api/v1/merchant/connectors/:id/test`

GET`/api/v1/merchant/connectors/:id/webhooks/inbounds`

GET`/api/v1/merchant/connectors/:id/webhooks/invalid`