Histórico da Página

Lançamento previsto para Abril/26! 🚀

Painel

titleColor	#FFF
titleBGColor	#2C004B
borderStyle	solid
title	Configuração:

Informações

✅ Pré-requisitos

Antes de iniciar a configuração, confirme que a loja possui:

um provedor principal de Pix já configurado e ativo
um provedor secundário de Pix configurado para contingência
credenciais válidas nos dois provedores
provedores aptos a processar Pix normalmente
validação operacional prévia do cenário esperado

Esses pontos são importantes para garantir que a contingência realmente possa assumir a operação quando necessário.

📍 Onde configurar

A configuração é realizada no Admin, dentro da tela de edição de meio de pagamento, na aba Contingência, em: Configs → Meios de Pagamento → Selecionar o meio de pagamento→ Contingência.

Nessa área, os principais campos relacionados à funcionalidade são:

Permitir uso como contingência
Provedor de contingência

⚙️ Como configurar

1. Defina qual provedor poderá ser usado como contingência

Acesse o cadastro do meio de pagamento que será utilizado como alternativa e localize o campo Permitir uso como contingência.

Esse campo define se o meio de pagamento poderá ser selecionado como provedor por outros meios de pagamento Pix como opção de fallback.

Na prática:

quando estiver permitido, ele poderá aparecer como alternativa de contingência
quando não estiver permitido, ele não poderá ser utilizado nesse papel

2. Habilite o uso como contingência

No campo Permitir uso como contingência, selecione a opção correspondente para liberar esse provedor como alternativa.

Esse ajuste é importante porque controla quais provedores estarão aptos a assumir a operação em caso de falha no provedor principal.

Nota
💡 Ponto de atenção: Se esse campo não estiver corretamente habilitado, o provedor pode não aparecer como opção no momento de definir a contingência.

3. Defina o meio de pagamento que terá contingência

Depois de habilitar o provedor, acesse o cadastro do meio de pagamento a ter contingência e, na mesma aba Contingência, localize o campo Provedor de contingência.

Nesse campo, selecione o provedor que assumirá a operação quando o esse meio de pagamento não conseguir concluir a cobrança.

4. Salve a configuração

Após preencher os campos necessários, salve a alteração no cadastro do provedor.

A partir disso, a loja passa a contar com a relação de contingência configurada entre o provedor principal e o provedor secundário

Informações

🧩 O que cada campo significa

Permitir uso como contingência

Define se aquele provedor poderá ser utilizado como alternativa para outros provedores Pix.
Use esse campo para indicar que o provedor está apto a assumir cobranças em cenário de fallback.

Provedor de contingência

Define qual provedor será acionado quando o provedor principal (meio de pagamento) não conseguir concluir a cobrança.
Use esse campo no cadastro do provedor principal para apontar qual será a alternativa de contingência.

Dica

🔍 Como validar a configuração

Antes de considerar a parametrização concluída, revise os seguintes pontos:

o Pix principal está ativo
o Pix de contingência está ativo
as credenciais dos dois provedores estão válidas
o provedor de contingência está homologado e apto para operação
a configuração atende ao comportamento esperado da loja
testes operacionais foram realizados antes da publicação

✅ Essa validação ajuda a reduzir riscos de falha no momento em que a contingência precisar entrar em ação.

UX:

🛒 Como a funcionalidade se comporta na loja

Depois de configurado, o Fallback para Pix atua de forma automática nos bastidores da operação.

O comportamento esperado é:

o comprador seleciona Pix normalmente no checkout
a plataforma tenta gerar a cobrança com o provedor principal
em caso de falha, podem ocorrer novas tentativas conforme a regra aplicada
se necessário, o provedor de contingência é acionado automaticamente

O cliente não precisa escolher entre provedor principal e contingência durante a compra.

Além disso, para evitar duplicidade na vitrine de pagamento, a opção usada apenas como contingência pode não aparecer separadamente no checkout quando já houver outra opção Pix disponível.

Fluxograma:

Image Added

📊 Como acompanhar no Admin

Quando uma venda for recuperada por fallback, a equipe pode acompanhar esse comportamento diretamente no detalhe do pedido.

No pedido, estará disponível a aba Fallback Pagamento, com informações como:

Operações Realizadas: histórico das tentativas no provedor principal e da transação de fallback
Motivo Principal: motivo da falha no provedor original
Último Erro: detalhe da mensagem retornada
Tentativas Realizadas: quantidade de tentativas antes da troca
Detalhes: visualização das informações de comunicação entre plataforma e provedores

🏷️ Identificação de pedidos com fallback (integração)

Pedidos concluídos com sucesso por meio da contingência recebem automaticamente a tag de sistema:

payment-fallback

Essa identificação ajuda a:

localizar pedidos que utilizaram fallback
criar filtros operacionais
monitorar estabilidade dos provedores
apoiar análises e conciliação financeira

Nota

icon	false

⚠️ Pontos de atenção

Ao configurar o Fallback para Pix, considere os seguintes cuidados:

os dois meios de pagamento (provedor e recebedor de contingência) precisam estar válidos e ativos
a configuração deve ser revisada periodicamente
a equipe operacional deve conhecer o comportamento da funcionalidade
o cenário deve ser testado antes da publicação em produção

Esses cuidados ajudam a garantir que a contingência esteja realmente pronta para uso quando necessária.