> ## Documentation Index
> Fetch the complete documentation index at: https://malga-develop.mintlify.site/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.

# Glossário 3DS

| Termo | Definição |
| - | - |
| **3-D Secure (3DS)** | Protocolo de autenticação para transações online que envolve três domínios (emissor, adquirente/lojista e interoperabilidade). |
| **3DS Server** | Servidor (lado PSP/lojista) que forma e assina as mensagens 3DS, interagindo com o DS e o ACS. |
| **ACS (Access Control Server)** | Servidor mantido pelo banco emissor responsável por autenticar o portador durante o desafio. |
| **AcsTransactionId** | UUID atribuído pelo ACS para a transação (challenge). |
| **AReq / ARes** | Mensagens de autenticação da versão EMV 3DS (substituem PAReq/PARes). |
| **BIN** | Bank Identification Number do adquirente, associado à bandeira. |
| **CAVV** | Cardholder Authentication Verification Value – código criptográfico gerado pelo emissor que comprova a autenticação. |
| **Challenge Flow** | Fluxo em que o emissor solicita uma ação extra (OTP, biometria, etc.); iniciado com stepUrl + token. |
| **Collect URL** | Endpoint do provedor para onde o front-end envia o JWT e coleta dados de dispositivo na etapa data collection. |
| **Data Collection** | Fase em que o navegador envia dados do dispositivo ao provedor via collectUrl, geralmente em iframe invisível. |
| **DirectoryServerTransactionId** | UUID atribuído pelo DS para a transação. |
| **DS (Directory Server)** | Componente que verifica se cartão, emissor e comerciante participam do 3DS e encaminha mensagens entre 3DS Server e ACS. |
| **ECI** | Electronic Commerce Indicator; valor que indica nível de autenticação e se há transferência de responsabilidade. |
| **EMV 3-D Secure (3DS2)** | Evolução do 3DS, definida pela EMVCo, que envia mais dados contextuais ao emissor e permite fluxos frictionless ou challenge. |
| **EMVCo** | Organização que mantém o padrão EMV 3DS e outras especificações de pagamento. |
| **Frictionless Flow** | Autenticação 3DS aprovada sem interação adicional do cliente. |
| **JWT / Token** | JSON Web Token devolvido no setup; é reenviado ao provedor na coleta e no challenge. |
| **Liability shift** | Transferência de responsabilidade por fraude do lojista para o emissor quando o 3DS é bem-sucedido. Quando usado MPI externo, a autenticação é de responsabilidade do parceiro, portanto devolveremos false para essa propriedade. |
| **MCC** | Merchant Category Code – código da atividade comercial. |
| **MPI (Merchant Plug-In)** | Módulo que integra o merchant ao 3DS (normalmente embutido no 3DS Server ou no PSP). |
| **PAReq / PARes** | Mensagens Payer Authentication Request/Response da especificação 3DS 1.x. |
| **Redirect URL** | Endereço do seu site para o qual o cliente volta após o desafio. |
| **RequiresLiabilityShift** | Flag na Malga que exige liabilityShift=true para aprovar a cobrança. |
| **Setup ID** | Identificador da sessão criada no setup 3DS2; vincula coleta de dados e cobrança. |
| **StepUrl** | URL do ACS para exibir a tela de desafio dentro de um iframe ou redirecionamento. |
| **ThreeDSServerTransactionId** | UUID gerado pelo 3DS Server para rastrear a transação. |
| **TransStatus** | Código de resultado da autenticação (ex.: Y = Sucesso, N = Falha, C = Challenge). |
| **UCAF** | Universal Cardholder Authentication Field – padrão de autenticação Mastercard. |
| **VEReq / VERes** | Mensagens de verificação de enrolamento na versão 1.x (Visa). |
| **XID** | Identificador de transação 3DS original (versão 1) ou adicional para algumas bandeiras. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.