> ## 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.

# Principais erros

Abaixo estão os principais erros que podem acontecer durante uma transação com 3DS, para te ajudar a identificar e entender melhor cada situação.

| Etapa | Mensagem | Descrição | Detalhe | O que fazer? |
| - | - | - | - | - |
| Setup | brand not found | A bandeira do cartão não foi encontrada ou não é suportada. [Veja aqui as bandeiras suportadas](https://docs.malga.io/documentations/tokenization/intro#bandeiras-aceitas) | Verifique as configurações do merchant Malga | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. |
| Setup | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | | Entre em contato com a Malga. |
| Enroll | invalid card expiration date | A data de validade do cartão é inválida | | Cliente precisa enviar outro cartão durante a compra |
| Enroll | acquirer merchantId not configured | O merchantId do adquirente não foi configurado | | Adicionar o merchantId no acquirer bin do provider na configuração do seu merchant Malga. [Veja aqui como fazer.](https://docs.malga.io/api-reference/merchants/criacao-de-novo-merchant-para-cobranca#body-providers-acquirer) |
| Enroll | acquirer bin not configured for this brand | O BIN do adquirente não foi configurado para a bandeira do cartão informada | Precisa adicionar um acquirer bin no provider do merchant | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. |
| Enroll | merchantName not configured | O merchantName não foi configurado | | Adicionar a informação de merchantName no merchant da Malga. [Veja aqui como fazer.](https://docs.malga.io/api-reference/merchants/criacao-de-novo-merchant-para-cobranca#body-merchant-name) |
| Enroll | brand not found | A bandeira do cartão não foi encontrada ou não é suportada | | Adicionar uma nova bandeira suportada no acquirer bin do provider na configuração do seu merchant Malga. |
| Enroll | Failed authentication eciRaw 07/00 | Falha na autenticação (ECI Raw 07/00) | Somente ECI 07 e 00 indicam que a autenticação foi feita com sucesso | Inicie o fluxo sem 3DS |
| Enroll | Authentication attempts unavailable by issuer | As tentativas de autenticação não estão disponíveis pelo emissor | O status indica que o cliente está habilitado para autenticação (como 3DS), mas ela não está disponível no momento. | O lojista pode tentar novamente ou seguir com a autorização, mas **assume o risco do chargeback**, pois **não há proteção sem autenticação**. |
| Enroll | Authentication error without challenge | Erro de autenticação sem desafio | A conta está habilitada para autenticação, mas o banco rejeitou a autenticação sem desafio. | O lojista **não pode seguir com a autorização** e deve **solicitar outro meio de pagamento**. Inicie o fluxo sem 3DS |
| Enroll | Authentication Unavailable | A autenticação não está disponível | Esse status indica que a conta **não é elegível para autenticação**, a autenticação foi ignorada ou houve **erro/timeout**. | É possível seguir com a autorização, mas **sem proteção contra chargeback**, pois **não há transferência de responsabilidade**. Você pode iniciar o fluxo novamente, mas em caso de erro é possível que o cartão não seja suportado, então a recomendação é seguir sem 3DS |
| Enroll | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | | Entre em contato com a equipe Malga. |
| Enroll | Access denied, invalid endpoint acquirerBIN, acquirerMerchantID not recognized | O merchantID ou acquirerBin não foi cadastrado junto à bandeira. | | Entre em contato com o provedor e solicite o cadastro do **Acquirer BIN** e do **Merchant ID**. Esse processo costuma ser automático para transações com **Visa**, mas no caso da **Mastercard** é necessário solicitar o cadastro. |
| Validate | Invalid PARes | O PARes (Payment Authentication Response) é inválido | Significa que a resposta da autenticação (PARes) recebida do banco emissor é inválida, corrompida ou malformada. Isso impede a finalização do processo de autenticação e pode resultar no bloqueio da transação. | Iniciar o fluxo 3DS do início. |
| Validate | Issuer unable to perform authentication | O emissor não conseguiu realizar a autenticação | Significa que o banco emissor **não conseguiu completar a autenticação do cliente**, possivelmente por problemas técnicos, indisponibilidade do sistema ou falta de suporte ao 3DS. Nesse caso, **não há proteção contra chargeback.** | Iniciar o fluxo 3DS do início. |
| Validate | Cardholder did not complete authentication | O portador do cartão não concluiu a autenticação | Significa que o **portador do cartão não finalizou o processo de autenticação**, seja por fechar a janela, não responder ao desafio ou deixar o tempo expirar. A transação pode falhar ou seguir sem proteção contra chargeback | Iniciar o fluxo 3DS do início. |
| Validate | cybersource api had an unexpected return | A API da Cybersource retornou um erro inesperado | Erro inesperado ao chamar o parceiro | Entre em contato com a Malga. |

## Retentativas e SetupId

**Importante:** Se uma transação 3DS2 falhar por qualquer motivo (timeout, erro de tokenização, erro de autenticação, etc.), **não é permitido reutilizar o mesmo `setupId`** para tentar novamente. O `setupId` retornado no setup é válido apenas para **uma única tentativa de cobrança**.

Para retentar uma transação que falhou, você deve:

1. **Criar um novo setup** — Chame novamente o endpoint `POST /v1/charges/3ds/setup` para obter um novo `setupId` [Veja aqui como criar o setup](/documentations/3ds2-malga/3ds-malga/transacao-3ds2-na-malga#passo-1-setup-da-sessão-3ds2)
2. **Realizar nova coleta de dados** — Execute novamente a etapa de coleta de dados do dispositivo (Passo 2)
3. **Criar nova cobrança** — Crie uma nova cobrança usando o novo `setupId` obtido

Tentar reutilizar o mesmo `setupId` em uma retentativa resultará em erro e impedirá o processamento da transação.


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