Fluxos - Configurar PIX Parcelado

O que é

O PIX Parcelado do Viagilize não é o PIX Parcelado oficial do Banco Central (em que o banco do cliente concede crédito e adianta o valor para o recebedor). É um plano de cobranças PIX agendadas: o sistema divide o valor da reserva em N pagamentos, cobra a primeira parcela no checkout (à vista, via PIX) e gera as demais como parcelas com data de vencimento futura. A cada vencimento, o cliente recebe link/cobrança PIX e paga normalmente - não há crédito embutido, não há juros automáticos cobrados pelo banco, e a confirmação pode ser automática (via meio de pagamento) ou manual (conferida pelo atendente).

Essa é a forma mais usada por agências para vender excursões de ticket alto para clientes que não têm cartão de crédito ou que preferem PIX. Quem chega neste fluxo está cruzando três áreas: Configurações > Pagamentos (ativa o método e define se vai via meio de pagamento ou manual), edição da excursão (define o limite máximo de parcelas e o acréscimo por parcela) e tela da reserva (monta ou ajusta o plano de pagamento por passageiro).

Como usar

1. Habilitar PIX no checkout

1. Vá em Configurações > Pagamentos no menu lateral.
2. Na aba Meio de pagamento de Pagamento, deixe um meio de pagamento ativo (Mercado Pago, Asaas, Pagar.me ou InfinitePay). É possível operar PIX Parcidlado também no modo PIX Direto sem meio de pagamento, mas a confirmação será manual a cada parcela.
3. Abra a aba Configurações (ícone de engrenagem) e role até Formas de Pagamento no Checkout.
4. Ligue o toggle PIX via {meio de pagamento ativo} (confirmação automática) ou o toggle PIX Direto (confirmação manual com sua chave PIX), conforme a estratégia.
5. Se você tem meio de pagamento ativo + PIX Direto habilitado, ligue também Processar PIX automaticamente pelo meio de pagamento para que o PIX Parcelado gere QR Code dinâmico do meio de pagamento (com webhook). Sem esse toggle, cada parcela é cobrada por QR Code estático manual e precisa ser confirmada à mão na tela da reserva.
6. Clique em Salvar Configurações no rodapé.

2. Definir o número máximo de parcelas na excursão

1. Vá em Excursões e abra a excursão desejada em modo Editar.
2. Na seção Financeiro, preencha:
   • Parcelas Máximas - número inteiro (sugestões comuns: 3, 6, 10, 12). É o teto que o cliente vê no checkout.
   • Acréscimo por parcela - opcional. Pode ser percentual (ex: 2%) ou valor fixo. Aplicado uma única vez sobre o valor base do pedido, compondo o valor_total_parcelado da Order quando o cliente escolhe PIX Parcelado.
3. Salve a excursão. A partir daí, o checkout mostra a opção PIX Parcelado em até Nx sempre que o meio de pagamento/PIX estiver habilitado.

3. Cliente compra e paga a primeira parcela

1. No checkout do site, o cliente seleciona PIX Parcelado e escolhe o número de parcelas (de 2 até o parcelas_max da excursão).
2. O OrderPagamentoController::index() calcula:
   • valor_total_parcelado (valor base + acréscimo, se houver).
   • valor_parcela = valor_total_parcelado / parcelas.
3. Na hora de pagar, o sistema cobra apenas o valor de uma parcela no PIX (a primeira), não o total. O pagamentoPix() gera QR Code via meio de pagamento (se pix_processar_via_gateway estiver ativo) ou QR Code estático (se PIX Direto manual).
4. Quando a primeira parcela é confirmada, a Order vai para status Parcial e o saldo restante fica pendente para os próximos meses.

4. Cobrar as parcelas seguintes

1. Cada parcela seguinte é representada como um ExcursaoPassageiroPagamento com status = pendente e data_vencimento futura. As parcelas aparecem na seção Plano de Pagamentos da tela da reserva.
2. Quando o cliente acessa novamente o link do pedido (recebido por WhatsApp/e-mail ou no portal Minha Conta), o index() recalcula o valor_pendente_real e gera novo QR Code com o valor da próxima parcela.
3. No fluxo via meio de pagamento, o webhook (Mercado Pago, Asaas, Pagar.me ou InfinitePay) confirma a parcela automaticamente e a Order soma o valor pago. No fluxo manual (PIX Direto), o atendente vai em Reservas > {reserva} > Plano de Pagamentos e clica em Confirmar ao identificar o crédito no extrato.

5. Montar ou ajustar manualmente o plano (atendente)

1. Abra a reserva em /admin/reservas/{passageiro}.
2. No card Financeiro, clique em Agendar Pagamentos.
3. No modal Configurar Plano de Pagamento, use Ações Rápidas (1x até 10x) ou monte parcela a parcela:
   • Valor de cada parcela.
   • Forma - para PIX Parcelado, escolha PIX em todas as parcelas.
   • Data de vencimento - escolha 30 dias (a partir de hoje) ou Mesmo dia (mesmo dia do mês mensalmente).
4. Garanta que o Total das Parcelas = Valor Pendente (tolerância de R$ 0,01) - sem isso, o botão Salvar Plano fica desabilitado.
5. Clique em Salvar Plano. As parcelas vão para o Plano de Pagamentos. O atendente pode mais tarde Editar, Excluir, Confirmar ou Compartilhar Recibo de cada uma (ver Pagamentos da Reserva).

Casos especiais

Diferença vs PIX à vista

No PIX à vista, o sistema gera uma única cobrança PIX no valor total do pedido. Cliente paga, Order vira Paga, fim. No PIX Parcelado, o sistema gera N cobranças ao longo do tempo, e a Order só vira Paga quando a última parcela for confirmada. PIX à vista é instantâneo; PIX Parcelado se estende por meses e exige acompanhamento (régua de cobrança, inadimplência, lembretes).

Diferença vs Cartão Parcelado

No Cartão Parcelado, o meio de pagamento captura uma única transação no cartão e o banco do cliente é quem divide o valor em N parcelas na fatura. A agência recebe normalmente o valor antecipado (descontada a taxa do meio de pagamento) em D+30 ou conforme o contrato - o risco de inadimplência fica com o banco emissor.

No PIX Parcelado do Viagilize, não há antecipação: a agência recebe parcela a parcela, mês a mês. Se o cliente parar de pagar a partir da 3ª parcela, a agência fica sem o restante e precisa decidir entre suspender o embarque ou cancelar a reserva.

Quando o cliente atrasa uma parcela

1. O cron enviar:lembretes-pagamento e os jobs de WhatsApp/Email enviam lembrete de vencimento (configurável em Configurações > Notificações Automáticas).
2. Se o Prazo para pagamento manual (aba Configurações > Regras de Reserva) estiver ativo, parcelas PIX manuais que não forem confirmadas dentro do prazo são canceladas automaticamente pelo job CancelarReservasExpiradas. Para PIX via meio de pagamento, o meio de pagamento invalida o QR Code conforme seu próprio prazo (~30 minutos no Mercado Pago).
3. O atendente pode usar a régua de cobrança em Reservas > {reserva} e, se for o caso:
   • Confirmar a parcela manualmente após receber o PIX fora do sistema.
   • Editar a parcela para ajustar valor/data combinada com o cliente.
   • Excluir a parcela e gerar nova via Agendar Pagamentos.
   • Cancelar a reserva inteira pela ação Cancelar Reserva quando fica claro que o cliente não vai concluir o plano. Veja Cancelar Reserva.

Regras por meio de pagamento

O comportamento do PIX Parcelado depende de qual meio de pagamento está ativo:

• Mercado Pago - Suporta PIX dinâmico nativo. Com o toggle Processar PIX automaticamente pelo meio de pagamento ligado, cada parcela gera QR Code via API do MP e o webhook confirma sozinho. Cancelamento automático em ~30 min se não pagar.
• Asaas - Suporta PIX dinâmico nativo. Mesmo comportamento do MP. O Asaas é o meio de pagamento com melhor experiência para cobranças recorrentes porque oferece régua de cobrança própria no painel do Asaas, em adição à régua do Viagilize.
• Pagar.me - Suporta PIX dinâmico nativo, fluxo equivalente ao MP.
• InfinitePay - Suporta PIX, mas não tem sandbox; o fluxo de Parcelado é viável só em ambiente real. A confirmação via handle é mais simples mas dá menos visibilidade que MP/Asaas.

Nenhum dos quatro meios de pagamento aplica juros automáticos entre parcelas - se você quer cobrar acréscimo, configure-o no campo Acréscimo por parcela da excursão; ele é absorvido uma vez no valor_total_parcelado e dividido igualmente entre as parcelas.

Sinal + Saldo (alternativa ao Parcelado)

Quando você quer cobrar apenas o sinal agora e deixar o saldo único para mais tarde (não múltiplas parcelas), use Sinal + Saldo em Configurações > Pagamentos > Configurações em vez de PIX Parcelado. O fluxo é mais simples (só 2 cobranças: sinal + saldo) e está documentado em Configurações - Pagamentos.

Re-parcelamento bloqueado

Depois que a Order tem qualquer pagamento real (valor_pago_real > 0) ou quando forma_pagamento = pix_parcelado, o OrderPagamentoController::index() não mostra mais a opção de PIX Parcelado ao cliente para o saldo restante. Isso evita o ciclo infinito "cliente parcela o saldo, paga uma parcela, parcela o novo saldo, e assim por diante". Para reagendar manualmente, o atendente usa Agendar Pagamentos dentro da reserva.

Pacote com vários passageiros do mesmo comprador

Quando o titular do grupo é responsável pelo pagamento de todos os passageiros da Order, o valor_pendente considerado pelo configurarPlanoPagamento é o do pedido inteiro (somando os passageiros), não o do passageiro individual. Isso mantém o plano coerente quando o comprador pagou tudo de uma vez ou quer dividir o total do grupo.

Erros comuns e como resolver

• "O total das parcelas (R$ X,XX) deve ser igual ao valor pendente (R$ Y,YY)."
  • Causa: a soma das parcelas no modal Configurar Plano de Pagamento não bate com o saldo pendente. Solução: ajuste valores manualmente ou use as Ações Rápidas (1x até 10x) para dividir automaticamente.
• "Apenas parcelas pendentes agendadas podem ser removidas." - Causa: tentativa de remover uma parcela já confirmada via plano. Solução: use Excluir no card do pagamento (vale apenas para pagamentos manuais confirmados) ou ajuste a próxima parcela.
• PIX Parcelado não aparece no checkout - Causa: a excursão está com parcelas_max igual a 1 (default) ou nenhum método PIX está habilitado em Configurações > Pagamentos > Configurações. Solução: edite a excursão e defina Parcelas Máximas maior que 1; ative pelo menos um toggle de PIX no checkout.
• Parcelas PIX manuais não cancelam automaticamente - Causa: o Prazo para pagamento manual está desligado. Solução: em Configurações > Pagamentos > Configurações > Regras de Reserva, ligue o toggle e defina um prazo (sugestões: 24h, 2 dias, 3 dias, 7 dias).
• Cliente pagou mas a parcela ainda aparece como Pendente - Causa: o fluxo é PIX Direto manual (não via meio de pagamento), o sistema não recebe webhook e depende de confirmação do atendente. Solução: abra a reserva, vá em Plano de Pagamentos, identifique a parcela e clique em Confirmar.
• Toast "Este pagamento não pode ser editado." ao tentar alterar uma parcela já paga via meio de pagamento. Causa: pagamentos com origem igual a mercadopago, asaas, pagarme ou infinitepay são imutáveis pelo admin. Solução: faça o estorno no painel do meio de pagamento e use Excluir se for o caso, ou registre um pagamento de ajuste manual.
• Cliente parcelou novamente sobre o saldo restante - Causa: versão antiga do controller que permitia re-parcelamento. Solução: a versão atual já bloqueia esse cenário no index(); se acontecer, abra suporte com o código da Order para investigação.

Onde encontrar

• URLs envolvidas:
  • /admin/configuracoes/pagamentos - habilitar PIX no checkout e definir prazos.
  • /admin/excursoes/{excursao}/edit - definir Parcelas Máximas e acréscimo.
  • /admin/reservas/{passageiro} - montar/ajustar plano e confirmar parcelas.
• Caminho no menu: Configurações > Pagamentos + **Excursões > {excursão}

  Editar** + Reservas > {reserva}.

• Permissões necessárias: ver as configurações/editar as configurações para habilitar o método, editar as viagens para definir o limite de parcelas, editar as reservas para montar e confirmar o plano.
• Módulo necessário: nenhum (faz parte do núcleo).

Veja também

• Pagamentos da Reserva - como montar o plano de pagamento, confirmar parcelas e gerar recibos.
• Configurações - Pagamentos - formas de pagamento do checkout, prazos de cancelamento e regra de Sinal + Saldo.
• Integrações - Meios de pagamento de Pagamento
  • credenciais e recursos de cada meio de pagamento antes de oferecer PIX Parcelado com confirmação automática.