Conectores

Um conector é um conjunto de credenciais configurado para um provedor de serviços de pagamento (PSP). Conectar o mesmo provedor duas vezes — digamos, um conjunto de credenciais em modo de teste e outro em modo produção, ou uma conta por país — produz dois conectores independentes. Tudo o que vem depois da configuração fala em termos de conectores, não de provedores: os perfis de roteamento referenciam conectores, e cada tentativa na linha do tempo de uma transação registra o connector_id por onde ela passou.

A Tokeflow orquestra as cobranças entre os seus conectores; ela não processa nem liquida fundos. O conector é onde você entrega à Tokeflow as credenciais do provedor que ela precisa para enviar cobranças em seu nome — e onde você configura os webhooks do provedor para que eventos assíncronos (confirmações de PIX, chargebacks, atualizações de estorno) voltem a chegar.

Como um conector é criado

Use GET /payment-providers para descobrir quais provedores estão disponíveis para conexão e quais métodos de autenticação cada um suporta, crie o conector e depois aponte seu roteamento para ele.

O objeto conector

Configuração do conector

config guarda substituições não sensíveis por conector:

Na atualização, cada chave é mesclada de forma independente: envie um array vazio ou omita card_brands para limpar a substituição de bandeiras, e envie installments_enabled: null para voltar ao estado não definido.

Conectores ativos e inativos

Um conector inativo (is_active: false) é ignorado pela avaliação de roteamento e é rejeitado como conector padrão de um perfil de roteamento por PATCH /routing/profiles/:id/default-connector. Desativar é a forma segura de tirar um conjunto de credenciais de rotação sem excluí-lo.

Quando a Tokeflow tira um provedor de pagamento de operação, os conectores dele ainda podem ser renomeados, ter as credenciais rotacionadas e ser desativados — mas um conector desativado não pode ser reativado (400) enquanto o provedor estiver inativo.

Credenciais recusadas

Se um provedor começa a recusar as credenciais de API de um conector — uma chave revogada, rotacionada ou restringida do lado do provedor —, a Tokeflow confirma a recusa junto ao provedor antes de agir. Uma vez confirmada, as renovações de assinatura roteadas para esse conector são colocadas em uma retenção de cobrança (billing hold) em vez de serem recusadas e irem para dunning. Salve novas credenciais com PATCH e a retenção é liberada; alterar apenas o webhook_secret não a libera.

Endpoints

Todos os endpoints de conector são delimitados sob o caminho do merchant. Com uma chave de Organization, merchant_id seleciona o merchant de destino; com uma chave de Merchant, ele deve ser o próprio merchant da chave.

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

Registra um conjunto de credenciais de PSP para o merchant. As credenciais são validadas junto ao provedor e armazenadas de forma criptografada. Use GET /payment-providers para listar os provedores disponíveis para conexão e os métodos de autenticação que cada um suporta.

Campos da requisição

O objeto credentials

O formato de credentials depende do provedor conectado. Alguns provedores exigem uma única chave de API; outros exigem um token de acesso mais um país, ou um par OAuth client_id/client_secret. Envie exatamente os campos que o seu provedor exige — chaves desconhecidas são recusadas, e a Tokeflow criptografa os valores em repouso e nunca os retorna por completo. O ambiente da chave precisa corresponder a is_test_mode: uma chave de produção em um conector de teste (ou o inverso) é rejeitada antes de qualquer coisa ser armazenada. Os slugs de provedor e seus requisitos exatos de credenciais estão listados para os seus provedores habilitados no Dashboard da Tokeflow.

Credenciais por provedor

Os campos exatos de credentials, o formato do webhook_secret e qualquer dado extra do pagador que um provedor exija são exibidos para os seus provedores habilitados no Dashboard da Tokeflow, e a equipe da Tokeflow pode confirmá-los para um provedor que você está prestes a habilitar. Três padrões cobrem o catálogo:

Seja qual for o padrão, cadastre o webhook_url do conector no painel do próprio provedor e envie payer_ip e um cliente completo nas cobranças com cartão dos provedores que os exigem — veja Provedores suportados.

Exemplo de requisição

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"] }
  }'

Exemplo de resposta — 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"] }
}

Trate webhook_url como um segredo

O webhook_url retornado autentica as chamadas do provedor por meio de um token embutido na query string. Qualquer pessoa com essa URL pode enviar eventos ao seu conector, então dê a ela o mesmo tratamento de uma API key:

• Cole-a apenas na configuração de webhooks do próprio provedor, sobre HTTPS.
• Nunca a coloque em um ticket, uma mensagem de chat, uma captura de tela, uma linha de log ou um bundle do lado do cliente.
• Se ela vazar, rotacione-a registrando o conector novamente e depois atualize a URL no dashboard do provedor.

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

Retorna uma lista paginada dos conectores de provedores de pagamento do merchant.

Parâmetros de consulta

Exemplo de requisição

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"

Exemplo de resposta — 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

Recupera um único conector. Retorna o objeto conector.

Exemplo de requisição

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

Exemplo de resposta — 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"] }
}

Um 404 (not_found_error) é retornado se o conector não existir ou não pertencer ao merchant.

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

Atualiza parcialmente um conector — credenciais, rótulo ou estado de habilitação. Somente os campos abaixo podem ser alterados; todos são opcionais.

Campos da requisição

Exemplo de requisição — rotacionar credenciais e renomear

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" }
  }'

Exemplo de resposta — 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"] }
}

Um 404 (not_found_error) é retornado se o conector não existir ou não pertencer ao merchant.

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

Remove o conector. Ele não pode estar referenciado por nenhum nó de roteamento nem ser o conector padrão de um perfil de roteamento — reaponte esses primeiro.

Exemplo de requisição

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

Códigos de resposta

Erros

Todo erro usa o envelope padrão. Os casos mais comuns para este recurso:

Consulte Erros para o envelope completo e o catálogo de tipos.

Relacionados

• Provedores de pagamento — descubra os provedores conectáveis e seus métodos de autenticação suportados.
• Perfis de roteamento — decida qual conector atende cada cobrança.
• Transações — veja os conectores em ação na linha do tempo de roteamento.
• Autenticação — provisione chaves e escopos.