Cartão de crédito é o meio de pagamento mais sensível de qualquer loja: é onde acontecem chargebacks, fraudes e perdas silenciosas. Este guia mostra como funciona a integração direta com a API Cielo eCommerce no Magento 2 — autorização, captura, 3-D Secure e reembolso — sem intermediários.

Entre todos os meios de pagamento, o cartão de crédito é onde mora o dinheiro — e também o chargeback. A pergunta certa para uma loja Magento 2 não é apenas "como autorizo um cartão", mas "como autorizo um cartão sem assumir o prejuízo da fraude?". A resposta tem nome: 3-D Secure. Este guia mostra como funciona a integração direta com a Cielo pela API oficial Cielo eCommerce, com a autenticação 3DS como protagonista.

Por que 3-D Secure vale o investimento

• O chargeback deixa de ser seu problema: quando a transação é autenticada com sucesso (indicador ECI 05), a responsabilidade por fraude transfere-se para o banco emissor. Para a loja, isso significa previsibilidade financeira em ticket alto.
• Mais aprovações: o emissor recebe dados verificados do dispositivo do comprador e decide com muito mais informação. Venda boa deixa de ser recusada por desconfiança.
• Sem fricção na maioria das vezes: no fluxo moderno do 3DS 2.0, a autenticação acontece nos bastidores — o cliente nem vê janela de senha. O módulo permite operar em modo Data Only (apenas informa o emissor) ou suprimir challenge conforme sua estratégia.
• Fraude sob controle: a camada de autenticação filtra o golpe antes da autorização, não depois.

Como o 3DS funciona dentro do checkout (na prática)

1. Coleta discreta do dispositivo: enquanto o cliente digita os dados do cartão, um script de fingerprint coleta sinais do dispositivo em segundo plano.
2. Autenticação junto ao emissor: ao clicar em finalizar, o módulo autentica a transação no MPI antes mesmo de criar o pedido. Na grande maioria dos casos, é tudo invisível para o comprador.
3. Credenciais de autenticação na autorização: a venda chega à API da Cielo acompanhada dos campos do 3DS (Cavv, Xid e indicador ECI) via ExternalAuthentication — é isso que garante o liability shift.
4. Autorização em tempo real: o pedido nasce autorizado (ou capturado, conforme configuração) com a transação amarrada ao pagamento no Magento.

O ciclo completo do crédito: autorizar, capturar, estornar

• Autorização vs. captura imediata: você escolhe entre capturar no fechamento do pedido ou autorizar primeiro e capturar depois — ideal para quem só quer capturar o que efetivamente despachou. Captura parcial é suportada.
• Cancelamento (void): enquanto a transação está apenas autorizada (antes da captura), o valor volta ao limite do portador sem custo.
• Estorno online (refund): depois da captura, o estorno é executado online na Cielo pelo próprio fluxo de credit memo do admin — com proteção contra duplicidade, rastreio do status de retorno e histórico completo no pedido.
• Parcelamento inteligente: número máximo de parcelas, parcela mínima, juros por conta do lojista ou do emissor e faixas sem juros — tudo calculado pela tabela Price tanto no checkout quanto na autorização.
• Tokenização do cartão: os dados sensíveis são tokenizados no navegador pelo Silent Order Post — o número do cartão nunca trafega pelos servidores da loja, reduzindo escopo PCI.

Checklist: o que exigir de um módulo profissional

• 3DS 2.0 nativo, com autenticação executada antes da criação do pedido (não como remendo pós-venda).
• Modos Data Only e supressão de challenge configuráveis — autenticação forte sem sacrificar conversão.
• Ciclo nativo do Magento: invoice, order state, credit memo — sem fluxo paralelo.
• Void e refund online com proteção contra estorno duplicado.
• Logs auditáveis sem expor PAN nem credenciais.
• Erros preservando a mensagem real da adquirente — nunca mascarar o motivo da negativa.

Os módulos HEX para Cielo no Magento 2

O módulo de crédito Cielo para Magento 2 cobre o ciclo completo — autorização, captura total ou parcial, void e refund online — direto pela API Cielo eCommerce, com ambiente de testes configurável. Já o módulo Cielo 3-D Secure adiciona a camada completa de autenticação do portador: fingerprint no checkout, autenticação junto ao emissor antes do fechamento do pedido e envio das credenciais 3DS na autorização — o conjunto que transfere a fraude para o emissor.

Instalação e configuração

Os módulos instalam via Composer e habilitam como métodos de pagamento nativos do Magento. A configuração pede as credenciais da API Cielo (MerchantId/MerchantKey) e, no módulo 3DS, os dados do estabelecimento no MPI (código, MCC e credenciais OAuth). O checkout segue o fluxo padrão do Magento — inclusive em one-step checkouts como Firecheckout. A homologação completa faz parte do serviço de implantação.

Perguntas frequentes

O módulo cobra taxa por transação?

Não. A integração é direta com a adquirente; as taxas são as negociadas entre você e a Cielo no seu contrato.

Preciso de certificado digital?

Não para a API Cielo eCommerce — apenas as credenciais MerchantId/MerchantKey. Diferente dos bancos (Itaú/Sicoob), que exigem certificado.

O cliente precisa digitar senha com o 3DS ativo?

Na maioria das transações, não. O 3DS 2.0 autentica pelos sinais do dispositivo sem intervenção. Quando o emissor exige desafio, ele aparece pontualmente — e há opção de suprimir challenge conforme sua política de risco.

O refund devolve o valor automaticamente pro cliente?

O módulo executa o estorno online na Cielo pelo credit memo do admin; o prazo de crédito na fatura depende do emissor (geralmente dias úteis).

Vale ativar 3DS para todas as vendas?

Para lojas de ticket alto, bens digitais ou histórico de chargeback, quase sempre sim: o custo da autenticação é ínfimo perto de um chargeback perdido. Lojas de ticket baixo podem avaliar o modo Data Only, que informa o emissor sem desafio.

Funciona com guest checkout?

Sim. Os módulos seguem o fluxo nativo de pagamento do Magento, com guest ou cliente logado, em qualquer checkout.