Integrações - Meios de pagamento de Pagamento

O que é

Os Meios de pagamento de Pagamento são os parceiros financeiros que processam PIX, cartão de crédito e boleto gerados pelo checkout do Viagilize. Conectar um meio de pagamento é o que transforma o site da agência de uma vitrine em uma loja com pagamento automático: o cliente reserva, paga, recebe a confirmação por e-mail/WhatsApp e a vaga é confirmada sem ninguém precisar conferir extrato no banco.

A página de configuração concentra todos os meios de pagamento em uma única aba (Meio de pagamento de Pagamento) dentro de Configurações > Pagamentos. Apenas um meio de pagamento pode ficar ativo por vez para o checkout, mas é possível deixar credenciais de vários salvas para alternar entre eles. Os quatro meios de pagamento oficialmente liberados para todos os empresas no momento são Mercado Pago, Asaas, Pagar.me e InfinitePay. Os meios de pagamento PagSeguro/PagBank e Valepay aparecem como Em Breve e só são liberados caso-a-caso pela equipe Viagilize (controlado por $gatewaysLiberadosPorTenant na view tab-gateways.blade.php).

Como usar

Conectar Mercado Pago

1. Vá em Configurações > Pagamentos no menu lateral e mantenha a aba Meio de pagamento de Pagamento.
2. No seletor Meio de pagamento Ativo para Checkout (topo da aba), escolha Mercado Pago.
3. Role até a seção Configurar Meios de pagamento e clique no card Mercado Pago para expandir.
4. Alterne entre Sandbox (Testes) e Produção nas abas internas do card.
5. Preencha os campos:
   • Public Key - chave pública usada pelo SDK do MP no frontend (sandbox começa com TEST-, produção com APP_USR-).
   • Access Token - token privado usado pelo backend para criar preferências, consultar pagamentos e PIX (sandbox TEST-, produção APP_USR-).
6. Em Modo, escolha Checkout Pro (cliente é redirecionado para o MP e juros de parcelamento são cobrados do comprador) ou Transparente (cliente preenche o cartão dentro do próprio site, juros assumidos pela agência).
7. Marque os Métodos de pagamento aceitos: PIX, Cartão e/ou Boleto.
8. Clique em Testar Configuração dentro do card. O sistema chama MercadoPagoService::testConnectionWithCredentials() com o token enviado e responde com toast verde (ok) ou vermelho (erro).
9. Clique em Salvar Configurações no rodapé. O badge do card muda para Sandbox (amarelo) ou Produção (verde).

Conectar Asaas

1. No seletor Meio de pagamento Ativo para Checkout, escolha Asaas.
2. Expanda o card Asaas na seção Configurar Meios de pagamento.
3. Alterne entre Sandbox (Testes) e Produção.
4. Preencha a API Key do ambiente escolhido. A chave do Asaas vem no painel em Integrações > API Key (formato $aact_... para produção, $aact_test_... para sandbox).
5. Em Modo, escolha Checkout (redireciona para a página do Asaas) ou Transparente (mantém o cliente no site).
6. Clique em Testar Conexão. O sistema chama AsaasService::testConnection() e mostra toast com o ambiente detectado.
7. Salve em Salvar Configurações.

Conectar Pagar.me

1. Selecione Pagar.me em Meio de pagamento Ativo para Checkout.
2. Expanda o card Pagar.me (logomarca lime do grupo Stone).
3. Alterne entre Sandbox (Testes) e Produção nas abas internas.
4. Preencha as credenciais:
   • Secret Key - chave privada do backend. Sandbox tem prefixo sk_test_, produção sk_.
   • Public Key - chave pública do frontend. Sandbox pk_test_, produção pk_.
5. Clique em Testar Configuração. O sistema chama PagarmeService::testConnectionWithCredentials() com o secret e o flag de sandbox.
6. Salve em Salvar Configurações.

Conectar InfinitePay

1. Selecione InfinitePay em Meio de pagamento Ativo para Checkout.
2. Expanda o card InfinitePay (badge Popular).
3. Diferente dos outros, o InfinitePay não tem distinção Sandbox/Produção - funciona em produção desde o cadastro.
4. Preencha apenas o campo Handle (InfiniteTag) - o nome de usuário do app InfinitePay (sem o $ inicial; se você colar com $ ou @, o sistema remove no update). Você acha o handle em app.infinitepay.io > Settings > External Checkout ou no canto superior esquerdo do app no celular.
5. Clique em Testar Conexão para validar que o handle existe no servidor da InfinitePay (InfinitiPayService::testConnection()).
6. Salve em Salvar Configurações.

Trocar o meio de pagamento ativo

1. Volte à aba Meio de pagamento de Pagamento.
2. No seletor Meio de pagamento Ativo para Checkout, escolha outro meio de pagamento (ou Nenhum para desativar o checkout online).
3. Salve. Reservas já em andamento continuam pelo meio de pagamento antigo até concluir ou expirar; apenas as novas usam o novo.

Casos especiais

Manter credenciais de vários meios de pagamento salvas

O sistema preserva as credenciais de todos os meios de pagamento configurados, mesmo trocando o Meio de pagamento Ativo. As credenciais ficam no JSON tenants.pagamentos por chave (mercado_pago, asaas, pagarme, infinitipay), preservadas pelo bloco $existingConfig no método update. Isso permite alternar entre Mercado Pago e Asaas, por exemplo, sem precisar colar tudo de novo.

Sandbox para testar antes de cobrar de verdade

Mercado Pago, Asaas e Pagar.me têm dois ambientes distintos. O Sandbox é o ambiente de testes oficial do meio de pagamento, com cartões e PIX falsos disponíveis na documentação do provedor. Nenhum pagamento sandbox cai na conta real. Use sempre Sandbox no início para testar o fluxo de checkout, o webhook de confirmação e o cancelamento automático antes de virar a chave para Produção.

InfinitePay sem ambiente de testes

A InfinitePay não disponibiliza sandbox público. O card mostra apenas um campo (Handle) e funciona já como produção. Para testar, faça uma reserva real de valor baixo (R$ 1,00) e cancele depois - o estorno é automático pelo painel da InfinitePay.

Mercado Pago Checkout Pro x Transparente

No Mercado Pago, o Modo controla como o cliente paga:

• Checkout Pro (pro) - o cliente é redirecionado para a página do MP, vê todas as bandeiras automaticamente e pode usar conta MP. Os juros do parcelamento são cobrados do comprador pelo próprio MP.
• Transparente (transparente) - o cliente preenche o cartão sem sair do site da agência. Os juros do parcelamento ficam na configuração da agência (bloco Taxas da aba Configurações).

Quando o modo é Checkout Pro, o bloco de taxas da página de Pagamentos simplifica o formulário para "MDR (taxa 1x) + máximo de parcelas" em vez do grid de 12 parcelas com CET.

Meios de pagamento em Em Breve (PagSeguro/PagBank e Valepay)

Os cards PagSeguro/PagBank e Valepay aparecem com o selo Em Breve e são desabilitados (não aceitam clique nem entram no seletor) para a maioria das empresas. A liberação é feita caso-a-caso pela equipe Viagilize via array $gatewaysLiberadosPorTenant em tab-gateways.blade.php. No momento, apenas você rotaazul tem InfinitePay, Pagar.me e Valepay liberados como ambiente de teste. Para solicitar liberação, abra um chamado no Suporte.

Meio de pagamento desativado mas com credenciais salvas

Se você escolher Nenhum em Meio de pagamento Ativo para Checkout, o checkout online é desligado - o cliente vê apenas os métodos manuais (PIX Direto, Cartão por Link, Transferência) e as credenciais salvas ficam dormentes. Útil ao migrar de provedor sem perder a configuração antiga.

Erros comuns e como resolver

• "Preencha o Access Token antes de testar a conexão" (toast amarelo) - Causa: clicou em Testar Configuração no Mercado Pago/Pagar.me/PagSeguro sem colar a credencial no ambiente atualmente selecionado (Sandbox ou Produção). Solução: cole o token/secret na aba correta e tente de novo.
• Status do card mostra "Erro" (vermelho) - Causa: o Mercado Pago retornou falha na chamada MercadoPagoService::testConnection() ao abrir a página (token expirado, revogado ou ambiente errado). Solução: abra o card, confira as credenciais do ambiente ativo, gere novas no painel do MP se necessário e clique em Testar Configuração para ver a mensagem detalhada.
• "Não configurado" (badge cinza) - Causa: o campo de credencial do ambiente ativo (sandbox ou produção, conforme o toggle) está vazio. Solução: marque o ambiente correto e cole a chave correspondente.
• Card aparece como "Em Breve" e não abre - Causa: o meio de pagamento (PagSeguro ou Valepay) não está liberado para você. Solução: abra um chamado no Suporte solicitando liberação.
• Toast "Erro ao testar conexão" sem detalhe - Causa: falha de rede entre o servidor do Viagilize e a API do meio de pagamento (fora do ar, firewall, DNS). Solução: aguarde alguns minutos e tente novamente; persistindo, verifique o status do meio de pagamento no site do provedor.
• Mercado Pago salvo mas checkout não usa o meio de pagamento novo - Causa: existe outro meio de pagamento selecionado em Meio de pagamento Ativo para Checkout. Solução: confira o seletor no topo da aba - só um meio de pagamento por vez fica ativo, mesmo com vários configurados.
• InfinitePay com handle errado retorna "Configurado" mas falha no checkout - Causa: o handle foi salvo sem validação de existência (o teste de conexão é leve). Solução: confirme em checkout.infinitepay.com.br/{seu-handle} se a página abre antes de habilitar no checkout real.

Onde encontrar

• URL: /admin/configuracoes/pagamentos
• Caminho no menu: Configurações > Pagamentos > aba Meio de pagamento de Pagamento
• Permissão necessária: ver as configurações para ver, editar as configurações para salvar/testar
• Módulo necessário: nenhum (faz parte do core)
• Rotas de teste: /admin/configuracoes/pagamentos/test-mercadopago, test-asaas, test-pagarme, test-infinitipay

Veja também

• Configurações - Pagamentos - página principal com Modo de Venda, Formas de Pagamento no checkout, taxas e regras de cobrança.
• Integrações e Conectores - visão geral das integrações do Viagilize.
• Webhooks - como o meio de pagamento notifica o sistema da aprovação/cancelamento de cada pagamento.
• Checklist de Configuração - marca Pagamentos como concluído depois da primeira configuração de meio de pagamento.