tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Conectores do Merchant

Gerencie as conexões de um Merchant com provedores de pagamento a partir do Dashboard — adicione credenciais, ative ou desative um conector e remova um.

Um conector é a conexão de um único Merchant com um provedor de pagamento: as credenciais, o ambiente para o qual ele aponta e se está atualmente habilitado. Esses endpoints dão suporte à tela de conectores do Dashboard.

Os conectores são aquilo para onde as regras de roteamento apontam — um perfil de roteamento só pode enviar uma cobrança para um provedor para o qual este Merchant tenha um conector. Desativar um conector o remove do roteamento imediatamente, de modo que as cobranças que iriam para ele passam em cascata para a próxima opção elegível.

Esses endpoints alimentam a interface do Tokeflow Dashboard. 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-merchant-id, identificando o Merchant em contexto, e o usuário autenticado deve ser membro com acesso a ele.

O objeto conector

Retornado pelos endpoints de listagem e recuperaçã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 a 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 de 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, um override de card_brands). Null 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/merchant/connectors

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

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/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). É necessário ser membro do Merchant.

Cria um 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 null 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. Note que createRoutingProfile e updateRoutingProfile atualmente não filtram por is_active, então um perfil ainda pode ser criado com um padrão inativo — 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 recebidos. 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/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"
  }'

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

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Exclui um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSim—

Exemplo de solicitação

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

Obtém um conector por ID.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSim—

Exemplo de solicitação

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

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

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Atualiza um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
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 recebidos. 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/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_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/merchant/connectors/:id/test

Merchant

Auth: Dashboard session (JWT bearer). É necessário ser membro do Merchant.

Testa as credenciais do conector contra o PSP.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSim—

Exemplo de solicitação

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

Obtém os webhooks recebidos de um conector.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
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ãoFiltra 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/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). É necessário ser membro do Merchant.

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

Parâmetros de caminho

CampoTipoObrigatórioDescrição
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/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"

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 do Merchant

Anterior

Clientes do Merchant

Próxima

Nesta página

O objeto conectorEndpointsGET /api/v1/merchant/connectorsPOST /api/v1/merchant/connectorsDELETE /api/v1/merchant/connectors/:idGET /api/v1/merchant/connectors/:idPATCH /api/v1/merchant/connectors/:idPOST /api/v1/merchant/connectors/:id/testGET /api/v1/merchant/connectors/:id/webhooks/inboundsGET /api/v1/merchant/connectors/:id/webhooks/invalidErrosRelacionados