Merchant Advice Codes (MAC)

Quando uma transação é recusada, os Merchant Advice Codes (MACs) fornecem orientações claras sobre se e quando uma nova tentativa é apropriada. Para apoiar a transparência e a tomada de decisões informadas, as APIs públicas da Yuno incluem códigos de resposta normalizados e brutos. Ao entender os MACs, os comerciantes podem identificar rapidamente o motivo de uma recusa e determinar as melhores ações a serem tomadas, como atualizar o roteamento ou as informações do cliente antes de tentar uma nova tentativa.

Lista de MACs

Essa tabela mapeia os Merchant Advice Codes normalizados da Yuno (merchant_advice_code e merchant_advice_code_message) com seus equivalentes da Mastercard, Visa e Elo. Use-o como referência para interpretar os motivos de recusa, definir regras de nova tentativa e aplicar estratégias de roteamento consistentes em todas as redes.

Campos MAC em transações

A API pública da Yuno inclui campos dedicados para facilitar o uso de Merchant Advice Codes.

MACs normalizados

A Yuno fornece um conjunto padronizado de Merchant Advice Codes que simplificam as respostas do provedor. Esses códigos permitem que você crie lógica de nova tentativa e regras de roteamento sem precisar gerenciar as variações exclusivas de cada provedor.

• transactions.merchant_advice_code: Um MAC Yuno-normalizado retornado quando uma transação é recusada. Esse código ajuda você a entender o motivo da recusa, se é possível tentar novamente e quais ações devem ser tomadas antes de tentar novamente o pagamento.
• transactions.merchant_advice_code_message: Esses campos complementam o merchant_advice_code vista acima, fornecendo uma explicação do código em termos legíveis por humanos. Essa mensagem permitirá que você aja de acordo com as informações sem precisar memorizar o significado de cada código.

MACs brutos

Juntamente com os valores normalizados, a Yuno também expõe os códigos e mensagens originais retornados pelos provedores. Esses campos brutos garantem total transparência e permitem que você solucione problemas ou siga orientações específicas do provedor quando necessário.

• transactions.provider_data.merchant_advice_code: O Merchant Advice Code original retornado diretamente do provedor de pagamento. Esse campo lhe dá acesso ao código bruto para total transparência e solução de problemas.
• transactions.provider_data.merchant_advice_code_message: Uma mensagem legível pelo provedor que explica o significado do MAC bruto. Use essa mensagem para entender a orientação específica do provedor sem precisar interpretar valores de código.

📘

Observe que esses campos estão localizados dentro dotransactions nas respostas da API.

Sobre novas tentativas

Quando uma compra com cartão é recusada, qualquer tentativa subsequente de concluir a compra usando o mesmo cartão é uma nova tentativa. As taxas e os limites para novas tentativas são definidos por cada rede de cartões. O número de tentativas antes da aplicação de taxas varia de acordo com a bandeira. Os comerciantes que não estiverem em conformidade poderão ser cobrados por transações excedidas.

O setor de pagamentos, juntamente com a ABECS, padronizou os códigos de resposta para recusas de transações com cartão. Essas tentativas são categorizadas em dois tipos:

• Reversível: Uma negação potencialmente temporária que pode mudar com o tempo. O emissor pode negar a transação devido a fundos insuficientes, problemas no sistema ou muitas tentativas de PIN sem sucesso.
• Irreversível: Qualquer autorização após uma recusa irreversível que não altere os campos de mensagem falhará. Isso pode significar que o cartão foi cancelado ou que a fraude foi confirmada.

A Visa, a Mastercard e a Elo atualizaram suas políticas para limitar as tentativas de nova tentativa de autorização após uma recusa e cobram taxas por tentativas além desses limites. Veja as regras de cada marca abaixo.

• Mastercard
• Visto
• Elo
• Outras marcas

Mastercard

A Mastercard lida com MACs como parte de seu programa de Excelência em Processamento de Transações (TPE), que tem dois componentes principais:

Tentativas excessivas de autorização

Tentativas excessivas de autorização da Mastercard O TPE tem como objetivo monitorar constantemente a utilização da rede para detectar e evitar o excesso de solicitações de autorização. A Mastercard também monitora transações aprovadas de valores muito pequenos (menos de uma unidade monetária) que são posteriormente reembolsados, pois podem indicar atividade de teste de cartão.

Esse monitoramento se aplica tanto às compras recusadas quanto às aprovadas. Uma nova tentativa é definida como qualquer nova tentativa de autorizar um pagamento usando o mesmo cartão e comerciante. As regras da Mastercard definem limites diários e mensais, dependendo da região (por exemplo, não mais do que 10 tentativas por dia ou 35 tentativas em um mês). Exceder qualquer um desses limites pode resultar em taxas adicionais.

Códigos de aviso ao comerciante (MACs) da Mastercard

A Mastercard usa os MACs para ajudar os comerciantes a entender quando é apropriado tentar novamente uma transação. Algumas recusas são irreversíveis, o que significa que a transação não deve ser tentada novamente, geralmente porque o cartão está fechado ou a fraude foi confirmada.

O programa TPE rastreia especificamente as novas tentativas após esses declínios irreversíveis, concentrando-se em dois códigos: MAC 03 ("Não tente novamente") e MAC 21 ("Sem ciclo de vida de novas tentativas"). Se você tentar processar o mesmo cartão e valor novamente após receber um desses códigos, a Mastercard poderá cobrar uma taxa.

Outros MACs, como os que indicam um problema temporário ou insuficiência de fundos, não acionam as taxas do MAC Transaction Excellence, mas você ainda pode ser cobrado pelo programa Excessive Authorization Attempts (Tentativas excessivas de autorização) se exceder os limites de novas tentativas.

Em alguns casos, os MACs recomendam aguardar um período de tempo específico antes de tentar novamente (por exemplo, "Retry after 24 hours"). Isso ajuda você a escolher o melhor momento para tentar novamente.

Veja todos os MACs da Mastercard e seus equivalentes Yuno-normalizados na lista de MACs.

Visto

Os MACs da Visa estão organizados em quatro categorias. O objetivo é manter o ecossistema equilibrado, reduzir as tentativas desnecessárias e exigir que os emissores usem códigos de recusa precisos e não genéricos.

📘

Taxas de visto

Como são irreversíveis, os códigos da categoria 1 incorrem em uma cobrança a partir da segunda tentativa. As categorias 2, 3 e 4 permitem até 20 tentativas em 30 dias, com taxas a partir da 21ª tentativa. Após 30 dias da primeira tentativa, qualquer nova tentativa será cobrada. As taxas da Visa são as seguintes:

• Doméstico: USD 0,10 + 13,83% de imposto
• Transfronteiriço: USD 0,25 + 13,83% de imposto

Categoria 1 (o emissor nunca aprovará)

Irreversível, sinaliza que o cartão foi cancelado ou nunca existiu, ou que a recusa é resultado de uma restrição ou erro permanente que bloqueará uma aprovação futura. Taxas da segunda tentativa.

• Os códigos comuns da categoria 1 podem incluir: 04, 07, 12, 15, 41, 43, 46, 57, R0, R1, R3

Categoria 2 (o emissor não pode aprovar no momento)

Reversível, significa que a negação resulta de uma condição temporária, como risco de crédito ou outras restrições do cartão que podem permitir que uma nova tentativa de transação seja aprovada. Alguns casos exigem ação do titular do cartão ou do emissor para remover a restrição antes da aprovação.

• Os códigos comuns da categoria 2 podem incluir: 03, 19, 39, 51, 52, 53, 59, 61, 62, 65, 75, 78, 86, 91, 93, 96, N3, N4, Z5, 5C, 9G

Categoria 3 (qualidade dos dados)

Reversível, é acionado por um erro de dados identificado pelo emissor. Os comerciantes devem revalidar os dados de pagamento antes de tentar novamente. Esses códigos de negação podem sinalizar riscos potenciais de fraude para os comerciantes.

• Os códigos comuns da categoria 3 podem incluir: 14, 54, 55, 70, 82, 1A, 6P, N7

🚧

Encargos da Categoria 3

Os comerciantes podem ter até 25.000 transações recusadas com erros de qualidade de dados (categoria 3) em um período de 30 dias. Se você ultrapassar esse limite, a Visa cobrará uma tarifa por cada transação adicional recusada nessa categoria.

Categoria 4 (códigos de resposta genéricos)

Reversível, inclui todos os outros códigos de resposta de recusa não incluídos nas categorias 1, 2 e 3, pois pode haver casos em que não haja valor de código de resposta para uma recusa específica. Os emissores podem usar outros valores de código de resposta definidos nas Especificações Técnicas da VisaNet. Entretanto, recomenda-se o uso mínimo.

Todos os MACs da Visa e seus equivalentes normalizados pela Yuno estão disponíveis na lista de MACs.

Elo

A Elo implementou regras em janeiro de 2025, com o objetivo de reduzir tentativas desnecessárias por parte de comerciantes e adquirentes. As transações são contadas do primeiro ao último dia do mês.

📘

Taxas Elo

R$ 0,80 por tentativa que exceder o limite do grupo.

Grupos Elo e regras de repetição

A Elo classifica os códigos reversíveis e irreversíveis em três grupos distintos:

📘

"CNPJ" refere-se à identificação do contribuinte brasileiro para o estabelecimento (CNPJ raiz em nível de grupo).

Consulte a lista detodos os MACsda Elo eos equivalentes normalizados da Yuno.

Outras marcas

• Códigos reversíveis: São permitidas novas tentativas para o mesmo cliente e cartão. Não há limite ou tempo limite pré-estabelecido.

🚧

Atenção

Antes de tentar novamente, siga as orientações recebidas na resposta de transação negada.

• Códigos irreversíveis: As autorizações para o mesmo cartão ou estabelecimento não serão permitidas após o recebimento da primeira resposta de recusa do emissor.

Roteamento com MAC

O comportamento de repetição deve ser implementado por meio de condições de roteamento. Atualize as rotas para incluir as novas condições MAC.

Ao criar um grupo de recusas no painel do Yuno, você pode optar por adicionar condições por Código de resposta ou por Código MAC.

🚧

Período de transição

Até que todas as integrações emitam MAC separadamente, alguns valores de MAC aparecerão em ambos os códigos de resposta e códigos de MAC. Isso é esperado enquanto a implementação do recurso é concluída.