Conectores e credenciais

Um conector e o parceiro (Cielo, Konduto, ClearSale). Uma conta de conector e o cadastro da sua organizacao nesse parceiro, com as chaves. Fluxos citam a conta, nunca a chave: trocar a chave da Konduto atualiza todos os fluxos que usam a conta, sem republicar nada.

Pagina Plugins

No painel, Plugins (menu Roteamento) e o catalogo de parceiros com o status de cada um no ambiente escolhido no topo (sandbox ou producao). Os cartoes sao agrupados por tipo - adquirentes, subadquirentes, gateways, antifraude, Pix, cofre de cartoes e atualizacao de cartoes - e mostram as capacidades em linguagem de negocio: cartao, Pix, boleto, split, link de pagamento, 3DS, antifraude, tokenizacao, validacao de cartao e estorno. A busca e os filtros (tipo, status e capacidade) ficam na URL, entao um recorte pode ser compartilhado por link.

EM BREVE e o parceiro com available: false no catalogo (status coming_soon ou disabled). Ele aparece para planejamento, com as capacidades previstas e o link da documentacao do parceiro, mas sem formulario de chaves: a API recusa criar conta para ele (422) e os nos do construtor de fluxos o mostram como "(em breve)", sem deixar escolher.

No detalhe de cada plugin ficam:

• as contas do ambiente, com saude, ultimo teste, interruptor de habilitar, Testar conexao, edicao das chaves (campo em branco mantem o valor atual) e remocao;
• Usado nos fluxos: os fluxos publicados que citam alguma conta do plugin, com link para cada um, e as etapas em que ele pode entrar (no Rotear para adquirente, Antifraude, Validacao de cartao, Autenticacao 3DS e o link de pagamento da fatura avulsa, conforme as capacidades);
• em cada conta, a secao Recursos, que liga e desliga o que a conta usa do plugin - ver Recursos por conta.

Plugins e fluxos usam a mesma conta

Nao existe "conta do fluxo" separada da "conta do plugin": as duas telas leem e gravam a mesma conta de conector (/v1/connector-accounts).

• Cadastrar as chaves dentro de um no do construtor (botao Cadastrar chaves ou Nova conta) cria a conta que aparece em Plugins.
• Cadastrar em Plugins deixa a conta pronta para ser escolhida nos nos.
• Desabilitar em Plugins aparece no no como "(desabilitada)" e tira a conta do roteamento na hora.
• Editar a chave num lugar vale para o outro e para todos os fluxos que usam a conta, sem republicar.

Catalogo

curl http://localhost:3333/v1/connectors?capability=antifraud_assessment \
  -H "Authorization: Bearer $MINSTREL_API_KEY"

Cada item traz capabilities, credentialsSchema (os campos que a conta precisa) e status: available, coming_soon (integracao em construcao) ou disabled. O painel monta o formulario de chaves a partir do credentialsSchema - conector novo nao exige mudanca no painel.

Os demais parceiros do catalogo aparecem como coming_soon (EM BREVE no painel).

Na Cielo, as credenciais legadas sopClientId e sopClientSecret não liberam coleta de cartão. Silent Order Post e sessões MPI estão suspensos por política de segurança, inclusive no sandbox da Cielo. As APIs autenticadas podem cobrar tokens obtidos no parceiro. Veja checkout e dados de cartão.

Para o 3DS e o Data Only, a Cielo tem outro microsservico, com credenciais proprias, geradas no mesmo lugar (Gestao API E-commerce, Microsservicos, 3DS). Todas sao opcionais na conta, mas o 3DS so roda com as cinco preenchidas. A emissão de sessões MPI para coleta na página está suspensa; as credenciais não liberam esse caminho:

O navegador do portador nunca recebe o ClientSecret: o Minstrel troca as credenciais por um token de uma autenticacao, e e so ele que vai para a pagina. Alem das credenciais, o recurso 3DS e Data Only precisa estar ligado na conta (veja Recursos por conta).

O Split de pagamento tem a sua propria credencial, splitClientSecret (o Client Secret do Split, que com o Merchant ID autentica as vendas divididas). Tambem e opcional na conta, mas o recurso so funciona com ela preenchida: veja Split da Cielo.

O link de pagamento tambem tem credenciais proprias, linkClientId e linkClientSecret (a API do Link e do Checkout da Cielo nao usa Merchant ID e Merchant Key). Opcionais na conta, mas o recurso so funciona com as duas preenchidas: veja Link de pagamento da Cielo.

Cadastrar uma conta

curl -X POST http://localhost:3333/v1/connector-accounts \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectorSlug": "konduto",
    "name": "Konduto - principal",
    "credentials": { "privateKey": "T..." },
    "verify": true
  }'

• As chaves sao validadas contra o credentialsSchema e gravadas cifradas (AES-256-GCM, vinculadas ao id da conta).
• Com verify: true, o Minstrel testa as chaves no parceiro antes de gravar; se o parceiro recusar, nada e salvo.
• A API nunca devolve a chave. Cada campo vem como { "configured": true, "secret": true, "hint": "••••••••" }; campos que nao sao segredo (ex.: Client ID) aparecem mascarados, o suficiente para reconhecer a conta.
• Na edicao (PATCH), campo omitido ou vazio mantem o valor atual: so o que for enviado e trocado.

Testar a conexao

Antes de salvar, com as chaves digitadas:

curl -X POST http://localhost:3333/v1/connectors/konduto/verify \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "credentials": { "privateKey": "T..." } }'

Ou de uma conta ja salva: POST /v1/connector-accounts/{id}/verify, que tambem atualiza a saude exibida no painel. A resposta separa tres situacoes, porque pedem acoes diferentes:

O teste e leve: nao cria pedido, nao gera cobranca e nao consome analise. Ha limite de 20 testes por minuto por organizacao.

Recursos por conta

O catalogo diz o que o plugin sabe fazer (capabilities). O que a conta pode fazer e menos: depende de contrato com o parceiro e da escolha de quem opera. Em Plugins, abra o conector, a conta e a secao Recursos: cada recurso mostra tres coisas.

Na Cielo:

No Minstrel Sandbox a validacao de cartao e o 3DS e Data Only vem ligados, para testar o no Validacao de cartao e o no de 3DS (e o debito, que o exige) sem contrato nem custo, e o resultado e simulado. O split do Sandbox tambem esta sempre disponivel, sem interruptor: ele existe so para testar a divisao (veja No Sandbox). A analise de fraude do Sandbox, ao contrario, vem desligada: ligada, ela passa a exigir os dados do cliente (veja Testar no Sandbox).

Por que existe a diferenca entre "o plugin sabe" e "a conta pode": ligar o Zero Auth numa conta sem o servico habilitado na Cielo geraria so respostas unavailable, e ligar sem querer um servico com custo seria surpresa na fatura do adquirente. Por isso o que depende de contrato nasce desligado.

Pela API, a conta traz config (os interruptores, com os padroes aplicados), effectiveCapabilities (as capacidades que a conta pode usar agora) e features (a matriz acima):

{
  "id": "ca_01HQ...",
  "connectorSlug": "cielo",
  "config": { "zeroAuthEnabled": true, "zeroAuthOnSave": false, "onAuthorizationExpiry": "notify" },
  "effectiveCapabilities": [
    "tokenize",
    "authorize",
    "capture",
    "void",
    "refund",
    "inquiry",
    "zero_dollar_auth"
  ],
  "features": [
    {
      "key": "zeroAuthEnabled",
      "title": "Validacao de cartao (Zero Auth)",
      "capability": "zero_dollar_auth",
      "availability": "available",
      "enabled": true,
      "requiresContract": true
    },
    {
      "key": "splitEnabled",
      "title": "Split de pagamento",
      "capability": "split",
      "availability": "available",
      "enabled": false,
      "requiresContract": true
    }
  ]
}

availability e available, coming_soon ou not_supported (o recurso pede uma capacidade que o conector nao tem). effectiveCapabilities e a lista que importa para o roteador e para o construtor de fluxos: uma conta com o Zero Auth desligado nao tem zero_dollar_auth ali e nao aparece no no Validacao de cartao.

Para mudar, PATCH /v1/connector-accounts/{id} com config. A atualizacao e parcial: so o que for enviado muda, e o resto continua como esta. null volta a chave ao padrao.

curl -X PATCH http://localhost:3333/v1/connector-accounts/ca_01HQ... \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "zeroAuthEnabled": true, "onAuthorizationExpiry": "void" } }'

Respondem 422: chave que o conector nao conhece, valor fora do tipo ou da lista, recurso Em breve e recurso que depende de outro desligado (ligar Validar ao salvar cartao sem a Validacao de cartao). Desligar a validacao de cartao desliga tambem o Validar ao salvar cartao.

Antifraude da Cielo

A Cielo faz a analise de fraude dentro da propria autorizacao: o Minstrel manda os dados do pedido no mesmo pedido de venda (bloco FraudAnalysis da API 3.0) e a Cielo aciona o provedor que voce contratou, Cybersource ou ClearSale. E diferente do no Antifraude do fluxo, em que o Minstrel consulta o provedor antes de autorizar: aqui nao ha chamada separada, nem credencial extra, e quem cobra a analise e a Cielo. O resultado, a revisao manual e o que acontece com a captura estao em Transacoes.

O que a conta precisa

• Contrato. O antifraude da Cielo (solucao Braspag) e contratado a parte. Sem ele, a Cielo responde Antifraud not configured (codigo 167) e o Minstrel devolve um erro tecnico dizendo que o antifraude nao foi habilitado para o Merchant ID. O erro nao e retentavel: ligue a analise so depois da habilitacao.
• Habilitacao no sandbox. A analise nao vem ativa na loja de sandbox da Cielo; o Atendimento a habilita, e so para quem contratou o produto.
• Homologacao. A Cielo valida transacoes de teste que levam os campos obrigatorios (1, 4, 9, 83 e 84, veja Campos que o Minstrel preenche) e, na Cybersource, aprova antes do go-live.
• Identificador do fingerprint. O braspag_<loja> que a Cielo (Braspag) fornece depois da contratacao. Sem ele o checkout transparente nao coleta a impressao digital do dispositivo (veja Impressao digital do dispositivo).

Configuracao da conta

Em Plugins, conta, Recursos, ou por PATCH /v1/connector-accounts/{id} com config. A analise so roda com fraudAnalysisEnabled ligado; as demais chaves so valem com ele.

Valor fora da lista (dado antigo) cai no padrao, em vez de virar um pedido que a Cielo recusaria. Campo de texto apagado volta ao padrao.

Quando a analise e enviada

As quatro condicoes valem ao mesmo tempo:

1. o no Rotear nao a dispensou (Antifraude da adquirente);
2. a conta tem fraudAnalysisEnabled ligado;
3. e cartao de credito: debito, Pix e boleto ficam fora;
4. o portador iniciou a transacao (initiator: "customer"): cobranca do lojista, como a de uma assinatura, nao e analisada.

Fora delas, nenhum dado extra do cliente (nascimento, endereco) sai do Minstrel.

Dados do cliente

Os dados vem do cadastro do cliente do pagamento (customerId). O que a Cielo exige, e o formato em que o Minstrel os entrega:

O endereco de cobranca so vai completo (rua, numero, CEP e bairro); incompleto, e omitido inteiro, porque a Cielo recusaria a venda inteira por um endereco pela metade. O de entrega vem do endereco de entrega do cadastro do cliente.

Se faltar um dado obrigatorio, a analise nao e enviada e a autorizacao segue normalmente. A avaliacao fica registrada como skipped, com a lista do que faltou (missingFields), no detalhe do pagamento. Dispensar em vez de falhar e proposital: faltar um telefone nao deve derrubar uma venda que voce quer receber. Para nunca vender sem analise, exija os dados do cliente na criacao do pagamento.

Ordem da analise

fraudAnalysisSequence e fraudAnalysisSequenceCriteria combinam assim:

Nas ordens em que a venda pode ser autorizada antes do veredito (AuthorizeFirst e AnalyseFirst com Always), o Minstrel a envia sem captura mesmo que voce tenha pedido captura automatica: capturar antes cobraria o portador de uma venda que o antifraude ainda pode recusar, e a recusa viraria estorno em vez de cancelamento. Com a captura manual, nada muda: a venda fica autorizada e voce captura quando quiser.

Campos que o Minstrel preenche

O antifraude trabalha com campos definidos pelo lojista (Merchant Defined Data, MDD). O Minstrel preenche os padroes abaixo; os marcados como obrigatorios sao os que a Cielo exige na homologacao:

O que voce manda em fraudAnalysis.merchantDefinedFields (ids de 1 a 89) vale mais que o padrao: o mesmo id troca o valor, e ids novos sao acrescentados. Use para o que o Minstrel nao sabe, como 4 com Call Center e 39 com o usuario do atendimento numa venda de call center, ou 9 com SIM e 22 com o codigo da loja numa retirada. O valor e cortado em 255 caracteres. A lista completa de campos esta na documentacao da Cielo (tabela de MDD).

Alem dos MDD, vao ao provedor o valor total do pedido, os items, isGift, returnsAccepted e shipping informados na criacao do pagamento (veja Transacoes). O IP e o navegador do portador so seguem junto com a impressao digital do dispositivo, porque a Cielo exige o fingerprint sempre que informa o bloco do navegador.

Testar no Sandbox

O Minstrel Sandbox simula a analise sem contrato nem custo. Ligue fraudAnalysisEnabled na conta Sandbox (vem desligado) e escolha o cenario pelo e-mail do cliente: a parte antes do @ que contem o marcador, sem diferenciar maiusculas.

Sem e-mail no cliente, a analise e dispensada (skipped, com email em missingFields). O Sandbox aceita as duas ordens de fraudAnalysisSequence: com AnalyseFirst, a recusa do antifraude vence uma recusa simulada do emissor; com AuthorizeFirst, o emissor decide primeiro, como na Cielo. Uma revisao simulada se resolve em cerca de um minuto, no primeiro ciclo do worker (veja o ciclo da revisao).

Cobranca

A tarifa da analise do adquirente e da Cielo, definida no contrato que voce tem com ela: o Minstrel nao a repassa nem a soma a fatura da plataforma. Na fatura do Minstrel entram so as analises do no Antifraude do fluxo.

Pontos em aberto

O que a documentacao da Cielo nao esclarece e esta sendo validado na homologacao:

• como simular Aceita, Recusada e Em revisao no sandbox da Cielo (a documentacao nao traz regra por nome, e-mail ou valor);
• qual Payment.Status a Cielo devolve numa venda recusada com AnalyseFirst (abortada ou nao finalizada);
• se a consulta da venda devolve a analise atualizada. Sem isso, uma revisao de venda com captura manual so e vista quando a Cielo captura ou cancela;
• se a analise aceita o cartao tokenizado (CardToken ou PaymentToken): o Minstrel envia a analise com o token, como faz com qualquer autorizacao;
• o formato do telefone na ClearSale.

Split da Cielo

O Split de Pagamento da Cielo divide a venda no proprio adquirente, entre o lojista principal (o master, dono da conta) e os recebedores (sellers) cadastrados na Cielo. Do lado do Minstrel, a divisao, a comissao, a captura parcial e o estorno estao em Split de pagamento; aqui ficam a conta, as credenciais e o que a Cielo exige.

O que a conta precisa

• Contrato do Split. O Split e um produto da Cielo (sobre a infraestrutura da Braspag), contratado a parte e com homologacao conduzida por ela. Sem a habilitacao do Merchant ID, a Cielo barra a venda (ReasonCode 38, MerchantSplitConfigurationNotFound) e o Minstrel devolve um erro tecnico dizendo isso.
• Client Secret do Split. Credencial propria, diferente do Merchant Key, do Silent Order Post e do 3DS. Gere no Portal Cielo E-commerce, em Empresas, Meus estabelecimentos, Configuracoes, Credenciais, Gerar novo Client Secret. Exige perfil Owner e autenticacao em duas etapas. O valor aparece uma unica vez, e gerar outro invalida o anterior. Cole em splitClientSecret, nas credenciais da conta.
• Sellers aprovados no onboarding do Split, com o SubordinateMerchantId de cada um (veja Sellers).
• O recurso ligado na conta (splitEnabled), abaixo.

A Cielo pode ainda exigir o soft descriptor (ReasonCode 39) e a analise de fraude (ReasonCode 40 e 41) numa loja de Split. O Minstrel traduz esses codigos em erro tecnico com a instrucao: informe o soft descriptor na venda e ligue o Antifraude da Cielo na conta.

Configuracao da conta

Em Plugins, conta, Recursos, ou por PATCH /v1/connector-accounts/{id} com config. Todo o resto depende de splitEnabled.

splitMasterMerchantId existe porque a documentacao da Cielo e ambigua sobre qual id o master usa na lista da API E-commerce: a FAQ cita o ClientId, e a pagina do token cita so Merchant ID e Client Secret. Se a homologacao pedir outro id, ele entra aqui, sem mudanca de codigo.

A conta com splitEnabled ligado e uma loja de Split, e tudo nela muda:

• toda venda (com ou sem divisao) vai como SplittedCreditCard ou SplittedDebitCard, no lugar de CreditCard e DebitCard. Uma venda sem parcelas vai sem SplitPayments: o valor inteiro fica com o lojista principal;
• autorizacao, captura, cancelamento, estorno e consulta autenticam com o token OAuth2 Bearer do Split.

Autenticacao

O Minstrel pede o token por OAuth2 client_credentials, com Authorization: Basic base64(MerchantId:ClientSecret), em auth.braspag.com.br (producao) ou authsandbox.braspag.com.br (sandbox).

• O token fica em memoria, um por ambiente e Merchant ID, e vale o expires_in da Cielo (20 minutos em producao) menos uma folga de 1 minuto. Trocar o Client Secret nas credenciais invalida o token guardado.
• Se a Cielo recusar um token guardado (401 ou 403, por exemplo porque o Client Secret foi gerado de novo no portal), o Minstrel pede outro e repete a chamada uma vez: a recusa de credencial vem antes de a Cielo processar qualquer coisa, entao a repeticao nao cobra duas vezes.
• Client Secret ausente com o split ligado e credencial recusada voltam connector_credentials_invalid, nao retentavel, com a instrucao de onde gerar ou conferir.
• A chamada leva o Bearer junto do Merchant ID e do Merchant Key de sempre. As paginas do Split mostram so o Bearer; se os dois esquemas podem viajar juntos esta nos pontos em aberto.

Sellers

O seller é o recebedor do lado da Cielo. Ele passa por KYC e validação do domicílio bancário. O Minstrel só libera split quando a consulta confirma onboarding final Approved, blocked: false e os mesmos documento, master e dados bancários. Um status isolado da análise de KYC não basta. Os sellers são brasileiros, com CPF ou CNPJ.

• O cadastro pode ser solicitado no Minstrel, em Split → recebedor → Cadastros por parceiro. Complete os dados adicionais da Cielo e acompanhe as pendências. O envio é assíncrono e não significa aprovação.
• Um seller já existente pode ser importado pelo SubordinateMerchantId (GUID), mas também exige confirmação pela API. O vínculo fica em registrations, separado por conta Cielo e ambiente. Os campos legados connectorAccountId e externalRecipientId não conferem aprovação manual.
• A sincronização usa consultas periódicas; não depende de notificações de onboarding da Cielo. A integração precisa de contrato de Split, credenciais habilitadas e homologação. Veja Cadastros por parceiro.
• Seller ainda nao aprovado ou bloqueado devolve o erro 326 Merchant blocked, que o Minstrel traduz (veja Erros do Split).
• Sandbox e producao da Cielo tem cadastros de seller separados: um id que nao existe no ambiente da conta volta o erro 298.

O que o Minstrel envia

• Em todas as listas a soma fecha exatamente o valor da operacao. Se nao fechar (soma acima do valor, recebedor repetido, o proprio lojista principal na lista de recebedores, SubordinateMerchantId fora do formato GUID), o Minstrel nem envia: e erro do nucleo, nao do parceiro, e volta connector_contract_violation.
• Fares leva a comissao do recebedor: Mdr e o percentual (550 basis points viram 5.5) e Fee e a tarifa fixa em centavos. Sem comissao cadastrada, o Fares nao vai e vale o acordo do seller na Cielo. Com so um dos dois, o outro vai zero.
• O liquido de cada recebedor vem da resposta da Cielo (SplitPayments[].Splits[]) e vira netAmount e feeAmount da parcela. Se a resposta nao traz a parte de um recebedor, nada e gravado para ele.
• liableForChargeback e chargeProcessingFee do recebedor nao tem equivalente na Cielo e nao sao enviados: todo chargeback e do lojista principal, e as tarifas do Split saem sempre da agenda dele.
• A Cielo permite um cancelamento parcial por transacao a cada 24 horas.

Erros do Split

Os erros abaixo sao de configuracao (do Split, do recebedor ou do valor) e nunca recusa do emissor. Por isso viram erro tecnico nao retentavel (connector_contract_violation), sem retentativa e sem fallback para outra conta, com a mensagem em portugues e o texto original da Cielo. Veja tambem o catalogo de erros.

Pontos em aberto do Split

A documentacao da Cielo nao esclarece o que segue, e a homologacao vai validar. O codigo foi escrito a partir da documentacao e ainda nao foi exercitado contra a Cielo:

• se a API E-commerce pede Payment.DoSplit junto de SplittedCreditCard. O Minstrel envia so o tipo Splitted*, que e a convencao da API E-commerce;
• se o Bearer pode viajar junto do Merchant ID e do Merchant Key;
• qual id o master usa na lista (MerchantId ou ClientId), hoje configuravel em splitMasterMerchantId;
• se o master entra em VoidSplitPayments (hoje entra, com o resto, para a soma fechar) e se o Reason: "HighRisk" do cancelamento por fraude pode ir junto de VoidSplitPayments no mesmo corpo;
• o que a Cielo faz com Fares incompleto (so Mdr ou so Fee), como arredonda o MDR por centavo e onde vai o MasterRateDiscountType;
• recorrencia: a Cielo diz que a venda recorrente nao aceita split no momento transacional (a divisao e pos-transacional, a cada cobranca). O Minstrel envia o split transacional tambem nas cobrancas recorrentes que ele mesmo dispara, e isso precisa ser confirmado. O split pos-transacional ainda nao existe no Minstrel;
• se uma venda sem divisao numa loja de Split pode ir como CreditCard comum, em vez de Splitted* sem SplitPayments.

Link de pagamento da Cielo

Gera, na Cielo, um link para o cliente pagar uma fatura avulsa. A pagina de pagamento e da Cielo (cielolink.com.br): o cliente digita o cartao la, e o Minstrel nunca o ve, nem em log nem no banco. Guarda so bandeira, BIN, final e os identificadores da transacao. E o caminho de cartao que a politica de coleta ainda permite. O uso, do lado do Minstrel, esta em Links de pagamento.

O que a conta precisa

Sem as credenciais com o recurso ligado, gerar o link falha com connector_credentials_invalid e a indicacao de onde gerar. Ligar o recurso nao muda nada na autorizacao de cartao da conta.

Testar: nao existe sandbox

As APIs do Link e do Checkout so existem em producao, com credenciais de producao; a conta de ambiente sandbox do Minstrel usa o mesmo endereco. Para testar, ligue o Modo Teste da loja no site da Cielo (E-commerce > Link de Pagamento > Configuracoes > aba Modo teste, e salve):

• cartao valido pelo algoritmo de Luhn com final 0 a 4 aprova e 5 a 9 nega, e ninguem e cobrado;
• a chave e da loja inteira: nao da para testar e vender de verdade ao mesmo tempo, e o Modo Teste precisa ser desligado antes de ir para producao;
• no Modo Teste o 3DS de credito nao funciona e o cancelamento parcial aceita valor maior que o total.

Como o Minstrel usa a API

• Criar: POST /v1/products/ com valor em centavos, validade (horario de Sao Paulo), um pagamento por link, parcelas e so os meios pedidos. Nenhum dado do cliente e enviado: ele digita nome, CPF e e-mail na pagina da Cielo. O returnUrl nao se aplica, porque a URL de retorno e da loja inteira.
• Confirmar: o Minstrel nao usa as notificacoes da Cielo (por loja, sem assinatura). O worker consulta os pedidos de cada link ativo a cada 5 minutos; pedido pago quita a fatura, e pedido so autorizado e capturado pelo Minstrel (exceto o que o antifraude da loja segurou para revisao). Pedido pendente, negado, cancelado ou expirado nao encerra o link: o cliente tenta de novo no mesmo endereco.
• Estornar e cancelar: a venda do link tem identificador proprio (checkout:<pedido>), e estorno, cancelamento e captura usam a API do Checkout (/v2/orders/{pedido}/void e /capture), nao a API 3.0. O estorno parcial pode se repetir ate o total.
• Cancelar o link: DELETE /v1/products/{id}; link ja removido conta como sucesso.

Limites deste caminho

• Sem split: o checkout hospedado nao recebe regras de divisao. Pedir divisao em captura, cancelamento ou estorno de uma venda do link falha com connector_unsupported_operation, em vez de deixar o valor inteiro com o lojista principal sem aviso.
• Antifraude e 3DS sao da loja, configurados no site da Cielo, e nao mudam por link. O antifraude integrado cancela sozinho o alto risco.
• So cartao de credito hoje: o catalogo nao oferece Pix nem boleto da Cielo.
• Sem idempotencia na criacao: a Cielo nao tem chave de idempotencia nem listagem de links por API. Depois de um timeout, o link pode existir sem o Minstrel saber; confira em Link de Pagamento > Meus links no site da Cielo.
• Link de assinatura com a Cielo continua indisponivel. O checkout hospedado so oferece a Recorrencia Programada, agendada e cobrada pela propria Cielo, e nao devolve token reutilizavel nem os identificadores da bandeira (IssuerTransactionId e TLID, este obrigatorio nas cobrancas iniciadas pelo lojista na Mastercard desde 23/10/2026). Usa-la criaria uma segunda agenda de recorrencia e tiraria do Minstrel a retentativa pela tabela ABECS. A tela de link de assinatura explica o motivo.

Pontos em aberto do link

O codigo foi escrito a partir da documentacao da Cielo e ainda nao foi exercitado contra ela: o corpo do pedido de token (a documentacao so descreve os cabecalhos), o formato exato da listagem de pagamentos do link, a unidade do valor em captura e cancelamento parcial (centavos, por analogia com o preco), o fuso das datas (lidas como horario de Sao Paulo) e se o preco do pedido vem no detalhe. A homologacao em Modo Teste valida cada um.

Particularidades de cada parceiro

Konduto. O ambiente e definido pela chave, nao pela URL: chave privada de teste comeca com T, de producao com P. O teste avisa quando a chave nao combina com o ambiente da conta. O score (0 a 1) vira 0 a 100; recomendacao NONE (pedido nao analisado) segue para revisao.

ClearSale. Usa os hosts global-api.clear.sale (producao) e sandbox-global-api.clear.sale (sandbox). A decisao vem por status; pedido ainda nao classificado (NVO) e consultado de novo ate o prazo do no, e analise manual (AMA) segue para revisao. ERR (erro de integracao) sai pela porta error.

Cielo. Gera link de pagamento no checkout hospedado dela (veja Link de pagamento da Cielo). Autoriza com CardToken da propria Cielo e marca credencial armazenada (CardOnFile) em toda cobranca com cartao salvo - as bandeiras recusam MIT sem essa marcacao. O codigo de retorno do emissor volta cru e e classificado pela tabela ABECS. A recusa do antifraude embutido, que nao vem do emissor, volta como ANTIFRAUD_REJECT (veja Antifraude da Cielo). Com o Split ligado, a venda vai como SplittedCreditCard ou SplittedDebitCard e a conta autentica por OAuth2 Bearer em toda operacao. O Zero Auth (validacao de cartao sem cobranca) cobre Visa, Mastercard e Elo, e exige o servico habilitado na Cielo - e um recurso da conta, desligado por padrao (ver Recursos por conta). A pre-autorizacao vence em 7 dias na Mastercard e em 15 nas demais bandeiras. O 3DS 2 e o Data Only usam o script MPI da Cielo, que roda no navegador do portador (Visa, Mastercard, Elo e Amex; o Data Only, so Visa e Mastercard), e o debito so e autorizado com o portador autenticado. O MPI usado e o V2, caminho legado: o V3, exclusivo de lojas PCI, ainda nao serve ao Silent Order Post.

Uso em fluxos

GET /v1/connector-accounts traz, em cada conta, usedByFlows: os fluxos publicados cuja versao em vigor cita a conta. E o mesmo dado que a pagina Plugins usa para mostrar "usado em N fluxos" e a lista Usado nos fluxos. Rascunho nao conta: o uso vale a partir da publicacao.

{
  "id": "ca_01HQ...",
  "name": "Sandbox principal",
  "enabled": true,
  "usedByFlows": [{ "id": "flw_01HQ...", "name": "Roteamento por faixa de ticket" }]
}

As contas sao por ambiente. A listagem ja vem filtrada pelo ambiente da credencial, e as rotas por id (GET, PATCH, DELETE e o teste de conexao) respondem 404 para conta do outro ambiente: com a credencial de producao nao se le nem se altera conta de sandbox.

Remover ou desligar

DELETE /v1/connector-accounts/{id} e recusado (409) quando a conta esta em um fluxo publicado, com a lista dos fluxos em meta.flows. Para tirar um parceiro do ar na hora, desabilite a conta (PATCH com enabled: false): o roteador deixa de escolhe-la e as outras contas do no assumem os pagamentos novos. Cartao salvo nela nao muda de adquirente, porque o token so vale onde foi gerado: a cobranca falha dizendo que a conta esta desabilitada ate que ela seja reabilitada. Se ela for a unica opcao do no de roteamento, as transacoes desse caminho falham por falta de conector disponivel. Na pagina Plugins, o painel ja avisa antes de tentar: conta em fluxo publicado tem a remocao bloqueada e oferece desabilitar no lugar.