✅ 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.
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
🧩 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.
🔍 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:
📊 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
✅ Checklist de configuração
Antes de publicar, revise este checklist:
- provedor principal de Pix configurado e ativo
- provedor de contingência configurado e ativo
- campo Permitir uso como contingência revisado
- campo Provedor de contingência preenchido
- credenciais dos dois provedores validadas
- comportamento esperado revisado
- testes operacionais realizados