saveinmed/saveinmed-frontend/IMPLEMENTACAO_MERCADOPAGO_CHECKOUT.md

Implementação Mercado Pago - Checkout SaveInMed

Visão Geral

Implementação completa da integração com Mercado Pago na aplicação SaveInMed, seguindo a estrutura da API BFF existente e o curl fornecido.

Arquivos Implementados

1. Serviço Mercado Pago (src/services/mercadoPagoService.ts)

Responsabilidades:

• Criar preferências de pagamento via BFF
• Verificar status de pagamentos
• Processar notificações de webhook
• Validar dados antes do envio
• Formatar valores e dados

Principais Métodos:

// Criar preferência de pagamento
criarPreferencia(pedidoId, itens, dadosComprador)

// Verificar status do pagamento
verificarStatusPagamento(paymentId)

// Processar notificação webhook
processarNotificacao(notificationData)

// Validar dados da preferência
validarDadosPreferencia(pedidoId, itens)

Endpoint BFF Utilizado:

• POST https://bff-dev.saveinmed.com.br/mercadopago/preference
• GET https://bff-dev.saveinmed.com.br/mercadopago/payment/{id}
• POST https://bff-dev.saveinmed.com.br/mercadopago/webhook

2. Componente Botão Mercado Pago (src/components/MercadoPagoButton.tsx)

Funcionalidades:

• Botão estilizado para pagamento via Mercado Pago
• Validação automática dos dados
• Estados de loading e erro
• Redirecionamento automático para o checkout do Mercado Pago
• Callbacks para sucesso e erro

Props:

interface MercadoPagoButtonProps {
  pedidoId: string
  itens: Array<{produto, quantidade}>
  dadosComprador?: {nome, email}
  onSuccess?: (preference_id, init_point) => void
  onError?: (error) => void
  disabled?: boolean
}

3. Páginas de Retorno

Página de Sucesso (src/app/pagamento/sucesso/page.tsx)

• Processa retorno de pagamento aprovado
• Exibe detalhes do pagamento e pedido
• Atualiza status do pedido
• Interface amigável com próximos passos

Página de Erro (src/app/pagamento/erro/page.tsx)

• Trata erros de pagamento
• Explica motivos comuns de falha
• Oferece sugestões e alternativas
• Botões para tentar novamente ou escolher outro método

4. Integração no Checkout (src/app/checkout/page.tsx)

Modificações Realizadas:

• Adicionada opção "Mercado Pago" na seleção de pagamento
• Lógica específica para processar pagamento via Mercado Pago
• Botão personalizado na etapa de confirmação
• Fluxo diferenciado para redirecionamento externo

Estrutura de Dados

Preferência Mercado Pago

{
  "back_urls": {
    "failure": "https://saveinmed.com.br/pagamento/erro",
    "success": "https://saveinmed.com.br/pagamento/sucesso"
  },
  "external_reference": "pedido-123",
  "items": [
    {
      "currency_id": "BRL",
      "id": "item-123",
      "quantity": 1,
      "title": "Nome do Produto",
      "unit_price": 99.90
    }
  ],
  "notification_url": "https://bff.saveinmed.com.br/mercadopago/webhook",
  "payer": {
    "email": "cliente@example.com",
    "name": "Cliente",
    "surname": "Teste"
  }
}

Resposta da API

{
  "success": true,
  "data": {...},
  "preference_id": "123456789-abc123",
  "init_point": "https://www.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abc123",
  "sandbox_init_point": "https://sandbox.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abc123"
}

Fluxo de Pagamento

1. Usuário Seleciona Mercado Pago

• Na etapa 2 do checkout, seleciona "Mercado Pago"
• Sistema avança para etapa 3 (confirmação)

2. Confirmação e Redirecionamento

• Usuário confirma dados na etapa 3
• Clica no botão "Pagar via Mercado Pago"
• Sistema cria preferência via BFF
• Redireciona para checkout do Mercado Pago

3. Processamento no Mercado Pago

• Usuário escolhe método (cartão, PIX, boleto)
• Completa o pagamento
• Mercado Pago processa transação

4. Retorno e Notificação

• Usuário retorna para URLs configuradas
• Webhooks notificam status via BFF
• Sistema atualiza pedido conforme resultado

URLs de Retorno

Sucesso

https://saveinmed.com.br/pagamento/sucesso

Parâmetros recebidos:

• payment_id: ID do pagamento no Mercado Pago
• status: Status do pagamento (approved, pending, etc.)
• external_reference: ID do pedido no sistema
• preference_id: ID da preferência criada

Erro

https://saveinmed.com.br/pagamento/erro

Parâmetros recebidos:

• payment_id: ID do pagamento (se disponível)
• status: Status do erro (rejected, cancelled, etc.)
• status_detail: Detalhes específicos do erro
• external_reference: ID do pedido

Webhook de Notificação

Endpoint: https://bff.saveinmed.com.br/mercadopago/webhook

Responsabilidade do BFF:

• Receber notificações do Mercado Pago
• Validar autenticidade das notificações
• Atualizar status dos pagamentos no sistema
• Processar ações automáticas (aprovação de pedidos, etc.)

Validações Implementadas

1. Dados da Preferência

• Pedido ID obrigatório
• Pelo menos um item obrigatório
• Preços maiores que zero
• Quantidades válidas
• IDs de produtos presentes

2. Estados do Botão

• Desabilitado se dados inválidos
• Loading durante criação da preferência
• Erro em caso de falha na API

3. Tratamento de Erros

• Mensagens específicas por tipo de erro
• Sugestões de correção
• Informações técnicas para debug

Benefícios da Implementação

1. Para o Usuário

• Múltiplas opções de pagamento em um só lugar
• Interface familiar do Mercado Pago
• Segurança e confiabilidade
• Parcelamento flexível

2. Para o Sistema

• Reduz complexidade de PCI compliance
• Aproveitamento da infraestrutura do Mercado Pago
• Notificações automáticas de status
• Integração via BFF existente

3. Para o Negócio

• Maior conversão de vendas
• Redução de abandono de carrinho
• Suporte a diversos métodos de pagamento
• Gestão centralizada via Mercado Pago

Configurações Necessárias

1. No BFF

• Configurar credenciais do Mercado Pago
• Implementar endpoints de preferência e webhook
• Validar autenticidade das notificações

2. No Mercado Pago

• Configurar URLs de retorno
• Configurar URL de webhook
• Configurar métodos de pagamento aceitos

3. No Frontend

• URLs de sucesso e erro configuradas
• Componente de botão implementado
• Serviço de API implementado

Monitoramento e Debug

1. Logs Implementados

• Criação de preferências
• Respostas da API
• Erros e exceções
• Redirecionamentos

2. Informações para Debug

• IDs de transação
• Status detalhados
• Parâmetros de retorno
• Dados técnicos nas páginas de erro

Próximos Passos

1. Testes

• Testar fluxo completo em sandbox
• Validar webhooks
• Testar cenários de erro

2. Monitoramento

• Implementar métricas de conversão
• Monitorar erros e falhas
• Acompanhar performance

3. Melhorias

• Implementar retry automático
• Adicionar analytics
• Otimizar UX baseado em dados

Conclusão

A implementação do Mercado Pago está completa e seguindo as melhores práticas:

• ✅ Integração via BFF existente
• ✅ Componentes reutilizáveis
• ✅ Tratamento completo de erros
• ✅ Páginas de retorno implementadas
• ✅ Validações robustas
• ✅ Logging detalhado
• ✅ Interface intuitiva

O sistema está pronto para testes e deploy, oferecendo uma experiência de pagamento moderna e segura aos usuários do SaveInMed.