> ## Documentation Index > Fetch the complete documentation index at: https://docs.malga.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga. > Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima. > Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação. > Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência". > Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas. > Sandbox é ambiente de testes e não afeta produção. # Começando em 3DS2 > Entenda como funciona o 3D Secure 2 (3DS2) na Malga, com fluxos com e sem desafio para autenticar o portador do cartão e reduzir fraudes em pagamentos. 3D Secure 2 é um protocolo da indústria de pagamentos que permite prevenir e eliminar o risco de fraude em pagamentos online ao permitir ao pagador se autenticar durante o processo de compra. O 3D Secure 2 visa também gerar a melhor experiência para o usuário, possibilitando que o fluxo seja mais fluido para o usuário final. ## 3DS nativo versus 3DS2 Malga Este guia cobre o **3DS nativo**: a cobrança envia o objeto `threeDSecure2` **sem** `setupId`, **sem** `mpi` e **sem** `dataOnly`. Nesse caso, a autenticação é conduzida pelo próprio provedor de pagamento. Para o 3DS nativo, o provedor precisa declarar **`operation=3ds2`**. Provedores que só têm `paymentTypes` com `3ds2_malga` (autorização com dados produzidos pela Malga ou por MPI externo) **não** são elegíveis para este fluxo. Se você precisa do fluxo com setup e coleta de dispositivo na Malga, use o [3DS2 Malga](/documentations/3ds2-malga/3ds-malga/pre-requisitos-configuracao). A comparação das quatro modalidades está no [hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga). ## Fluxo de cobrança com 3D Secure 2 Para utilizar o 3D Secure 2 nativo em suas transações, credencie-se em um provedor com **`operation=3ds2`**. Consulte a capacidade exigida por modalidade na [matriz do hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) e verifique os badges distintos de **3DS nativo** e **3DS2 Malga** na [tabela de meios de pagamento](/documentations/type-tables/payment-methods-by-providers). Configure esse provedor no merchant (ou no fluxo de pagamentos) e adicione o objeto `threeDSecure2` ao corpo da cobrança com os campos requeridos — **sem** `setupId`, `mpi` ou `dataOnly`. Verifique nossa [**API**](/api-reference/charges/listar-cobrancas) para detalhes. Tanto o fluxo sem desafio quanto o fluxo com desafio utilizam redirecionamento para fazer a autenticação do portador do cartão.
Nos exemplos a seguir iremos nos referir a 3D Secure 2 como 3DS2
* Fluxo sem desafio * O portador preenche os dados do cartão no checkout do estabelecimento. * O estabelecimento aciona a solução 3DS2 da Malga via API `/charges` para criar a transação com 3DS2. * A solução 3DS2 da Malga envia ao provedor de autenticação os dados do comprador. * O provedor de autenticação se comunica com a bandeira para processar a autenticação. * A bandeira identifica o emissor do cartão, e envia os dados do comprador para análise. * A bandeira retorna os dados de autenticação silenciosa ao provedor. * O provedor retorna dados para autenticação silenciosa à Malga. * A Malga retorna uma transação com status `pending` ao estabelecimento com dados adicionais para autenticação. * O estabelecimento utiliza os dados para autenticação por redirecionamento. * Para transações autorizadas, o redirecionamento será executado automaticamente pelo browser retornando para o endereço informado em `redirectURL`, não precisando da interação do portador do cartão. * O provedor de autenticação retorna o resultado da autorização silenciosa à solução 3DS2 da Malga via webhook. * A Malga retorna o resultado da autorização ao estabelecimento via webhook. * O estabelecimento informa o resultado do pagamento. * Fluxo com desafio * O portador preenche os dados do cartão no checkout do estabelecimento. * O estabelecimento aciona a solução 3DS2 da Malga via API `/charges` para criar a transação com 3DS2. * A solução 3DS2 da Malga envia ao provedor de autenticação os dados do comprador. * O provedor de autenticação se comunica com a bandeira para processar a autenticação. * A bandeira identifica o emissor do cartão, e envia os dados do comprador para análise. * O emissor identifica o portador como um possível risco, desta forma, exige o desafio e retorna os dados de Autenticação. * A bandeira retorna os dados de autenticação ao provedor. * O provedor de autenticação retorna os dados de autenticação à solução 3DS2 da Malga. * A Malga retorna uma transação com status `pending` ao estabelecimento com dados adicionais para autenticação. * O estabelecimento apresenta a tela da autenticação via lightbox. * O portador resolve o desafio na tela do emissor. * O emissor retorna o resultado da autenticação à bandeira. * A bandeira retorna o resultado da autenticação ao provedor de autenticação. * O provedor de autenticação retorna o resultado da autenticação à solução 3DS2 da Malga via webhook. * A Malga retorna o resultado da autorização ao estabelecimento via webhook. * O estabelecimento informa o resultado do pagamento. ## Diagrama de sequência Diagrama 3DS2 ## Diagrama de fluxo Fluxo 3DS2 ### Capacidade exigida O 3DS nativo exige provedor com **`operation=3ds2`**. Use a [matriz de modalidades do hub 3DS2](/documentations/3ds2-malga/intro#modalidades-de-3ds-na-malga) como fonte dessa regra e a [tabela de meios de pagamento](/documentations/type-tables/payment-methods-by-providers) para identificar o badge de **3DS nativo**. O badge de **3DS2 Malga** representa outra capacidade: para autorização com `setupId` ou MPI externo, o provedor precisa declarar `paymentTypes=3ds2_malga`, sem exigir `operation=3ds2`. ## Related topics - [Começando em 3DS2 Malga](/documentations/3ds2-malga/intro.md) - [3DS2 Agnóstico no Link de Pagamento](/documentations/payment-link/3ds2.md) - [Configurar a Content Security Policy (CSP) para o 3DS2](/documentations/3ds2-malga/3ds-malga/urls-liberacao.md) - [Nov 25, 2025 - 3DS2 Malga no Link](/release-notes/2025-11-25-Release-Notes.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.