tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Conectores da Organization

Veja e gerencie os conectores de provedor de pagamento entre os Merchants da Organization a partir do Dashboard.

Esses endpoints dão à Organization uma visão entre Merchants dos conectores — a conexão de cada Merchant com um provedor de pagamento. A partir daqui, um administrador da Organization pode revisar a cobertura e gerenciar os conectores sem alternar Merchant por Merchant.

Um conector ainda pertence a exatamente um Merchant; a visão da Organization apenas os agrega. Desativar um conector o remove imediatamente do roteamento desse Merchant.

Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também carregam o header x-organization-id, e o usuário autenticado deve ser membro dessa Organization.

O objeto de conector

Retornado pelos endpoints de listagem e obtenção desta página.

CampoTipoDescrição
idstringID do conector.
merchant_idstringID do Merchant.
provider_slugstringSlug do provedor de pagamento.
payment_provider_idstringID do provedor de pagamento por trás do conector — continua legível depois que o provedor deixa de ser listado como ativo.
namestringNome do conector.
country_codestring | nullCódigo de país ISO 3166-1 alpha-2.
auth_methodstringMétodo de autenticação (api_key para V1).
is_test_modebooleanSe este é um conector em modo de teste.
is_activebooleanSe o conector está ativo.
created_atstringTimestamp de criação do conector. (ISO 8601 UTC).
webhook_urlstring | nullURL do webhook para receber eventos do PSP. Configure isso no dashboard do seu PSP.
has_webhook_secretbooleanSe os webhooks recebidos do provedor podem ser verificados — um webhook_secret está armazenado, ou o provedor assina com uma chave que já está em credentials (alguns provedores assinam com a chave secreta da conta).
configobject | nullConfiguração opcional não sensível por conector (por exemplo, override de card_brands). Nulo quando nenhum override está definido, caso em que o SDK recorre ao default_supported_card_brands do PSP. Também aceita installments_enabled — veja Configuração do conector.

Endpoints

GET/api/v1/org/connectors

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Lista os conectores do Merchant.

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.

Exemplo de solicitação

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"

Exemplo de resposta — 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). É necessário ser membro da Organization.

Cria um novo conector.

Campos da solicitação

CampoTipoObrigatórioDescrição
provider_slugstringSimSlug do provedor de pagamento. Um dos valores provider_a, provider_b, provider_c, provider_d, provider_e.
namestringSimNome do conector.
country_codestringNãoCódigo de país ISO 3166-1 alpha-2. Aceita nulo para PSPs não específicos de país.
is_test_modebooleanSimSe este conector está em modo de teste.
is_activebooleanNãoSe o conector está ativo na criação. Padrão true quando omitido. Um conector inativo é ignorado pela avaliação de roteamento e é rejeitado por PATCH /routing/profiles/:id/default-connector. Observe que createRoutingProfile e updateRoutingProfile atualmente não filtram por is_active, portanto um perfil ainda pode ser criado com um padrão inativo — as cobranças nele então falham no momento da resolução.
credentialsobjectSimCredenciais específicas do provedor para o provedor conectado — por exemplo, uma chave de API, ou um token de acesso mais o país. Os campos exatos dependem do provedor. Os valores são criptografados em repouso e nunca retornados por completo.
webhook_secretstringNãoSegredo de assinatura de webhook do PSP para verificar webhooks de entrada. O formato depende do provedor: o Provider A usa whsec_...; o Provider B espera um objeto JSON em string {"username":"...","password":"..."} usado para verificação HTTP Basic Auth; alguns provedores esperam o token de acesso definido no webhook no painel deles, e outros não precisam de nenhum (assinam com a chave secreta da conta).
configobjectNãoConfiguração opcional não sensível por conector. Suporta card_brands (restringe as bandeiras expostas ao SDK) e installments_enabled (true oferece parcelas no checkout, false as recusa, não definido aceita apenas parcelas pedidas via API). Veja Configuração do conector.
auth_methodstringSimUm dos valores api_key, oauth2.

Exemplo de solicitação

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

Exemplo de resposta — 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). É necessário ser membro da Organization.

Exclui um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Exemplo de solicitação

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

Exemplo de resposta — 204 No Content

Um corpo vazio é retornado em caso de sucesso.

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

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Obtém o conector pelo ID.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Exemplo de solicitação

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

Exemplo de resposta — 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). É necessário ser membro da Organization.

Atualiza um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Campos da solicitação

CampoTipoObrigatórioDescrição
namestringNãoNome do conector.
is_activebooleanNãoSe o conector está ativo.
credentialsobjectNãoCredenciais específicas do provedor para o provedor conectado — por exemplo, uma chave de API, ou um token de acesso mais o país. Os campos exatos dependem do provedor. Os valores são criptografados em repouso e nunca retornados por completo.
webhook_secretstringNãoSegredo de assinatura de webhook do PSP para verificar webhooks de entrada. O formato depende do provedor: o Provider A usa whsec_...; o Provider B espera um objeto JSON em string {"username":"...","password":"..."} usado para verificação HTTP Basic Auth; alguns provedores esperam o token de acesso definido no webhook no painel deles, e outros não precisam de nenhum (assinam com a chave secreta da conta).
configobjectNãoConfiguração opcional não sensível por conector. Mesclada chave a chave. Passe um array vazio ou omita card_brands para limpar o override de bandeiras; passe installments_enabled: null para voltar o parcelamento ao estado não definido. Veja Configuração do conector.

Exemplo de solicitação

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_provider_key_rotated",
      "account_id": "acct_456"
    },
    "webhook_secret": "whsec_abc123...",
    "config": {
      "card_brands": [
        "visa",
        "mastercard",
        "elo"
      ],
      "installments_enabled": true
    }
  }'

Exemplo de resposta — 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). É necessário ser membro da Organization.

Testa as credenciais do conector contra o PSP.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Exemplo de solicitação

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). É necessário ser membro da Organization.

Obtém os eventos de webhook de entrada de um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.
statusstringNãoFiltrar por status do evento de webhook
fromstringNãoLimite inferior inclusivo para received_at (ISO 8601)
tostringNãoLimite superior inclusivo para received_at (ISO 8601)

Exemplo de solicitação

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). É necessário ser membro da Organization.

Obtém os eventos de webhook inválidos de um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
connector_idstringSim—

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.
fromstringNãoLimite inferior inclusivo para received_at (ISO 8601)
tostringNãoLimite superior inclusivo para received_at (ISO 8601)

Exemplo de solicitação

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"

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTPSignificado
400Parâmetros inválidos ou um estado que não permite esta operação.
401Token de sessão do Dashboard ausente, expirado ou inválido.
403Autenticado, mas o usuário autenticado não tem acesso a esta entidade.
404O registro não existe ou não é visível para esta entidade.

Relacionados

Trilha de auditoria da organização

Anterior

Clientes da Organization

Próxima

Nesta página

O objeto de conectorEndpointsGET /api/v1/org/connectorsPOST /api/v1/org/connectorsDELETE /api/v1/org/connectors/:connector_idGET /api/v1/org/connectors/:connector_idPATCH /api/v1/org/connectors/:connector_idPOST /api/v1/org/connectors/:connector_id/testGET /api/v1/org/connectors/:connector_id/webhooks/inboundsGET /api/v1/org/connectors/:connector_id/webhooks/invalidErrosRelacionados