Lançamento previsto para Abril/26! 🚀


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

💡 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

(piscar o olho)

🧩 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 é:

  1. o comprador seleciona Pix normalmente no checkout
  2. a plataforma tenta gerar a cobrança com o provedor principal
  3. em caso de falha, podem ocorrer novas tentativas conforme a regra aplicada
  4. 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.

📊 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

⚠️ 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.


✅ 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