Solidus Mercado Pago 2 🇧🇷

Version Ruby Rails

Integração moderna do Mercado Pago com Solidus, oferecendo suporte completo para pagamentos via cartão de crédito e PIX, com interface otimizada e recursos avançados.

🚀 Funcionalidades

  • ✅ Pagamentos com Cartão de Crédito

    • Integração com Mercado Pago SDK-JS
    • Suporte a cartões salvos
    • Autenticação 3D Secure
    • Múltiplas parcelas
    • Interface responsiva com Payment Brick

  • ✅ Pagamentos via PIX

    • Geração automática de QR Code
    • Código copia e cola
    • Verificação automática de status
    • Expiração configurável

  • ✅ Recursos Avançados

    • Gerenciamento de clientes
    • Sincronização automática de status
    • Interface administrativa completa
    • Logs detalhados de transações
    • Suporte a reembolsos e cancelamentos

  • ✅ Compatibilidade

    • Solidus 3.0+
    • Rails 6.0+
    • Ruby 2.7+
    • Suporte a User e Spree::User

📦 Instalação

1. Adicione a gem ao seu Gemfile

gem 'solidus_mp_dois'

2. Execute o bundle install

bundle install

3. Execute o gerador de instalação

rails generate solidus_mp_dois:install

Este comando irá:

  • Instalar a gem mp_api
  • Adicionar as migrações necessárias
  • Configurar o Importmap para o SDK do Mercado Pago
  • Copiar os controladores Stimulus necessários
  • Executar as migrações (opcional)

4. Execute as migrações (se não executadas automaticamente)

bin/rails railties:install:migrations FROM=solidus_mp_dois

⚙️ Configuração

1. Adicione os métodos de pagamento no painel administrativo

Acesse o painel administrativo do Solidus:

  1. Vá para Configurações > Métodos de Pagamento
  2. Clique em Novo Método de Pagamento
  3. Selecione o tipo desejado:
    • SolidusMpDois::MpCard para cartão de crédito
    • SolidusMpDois::MpPix para PIX

2. Configure as credenciais do Mercado Pago

Para cada método de pagamento, configure:

  • Public Key: Sua chave pública do Mercado Pago
  • Access Token: Seu token de acesso do Mercado Pago
  • Statement Descriptor: Descrição que aparece na fatura (opcional)

3. Configure o frontend (Stimulus)

Se você estiver usando Importmap, os controladores já foram configurados. Para outros bundlers:

// application.js
import "controllers/card_payment_brick_controller"
import "controllers/payment_brick_controller"
import "controllers/three_ds_controller"

🎯 Uso

Pagamentos com Cartão de Crédito

Payment Brick (múltiplos métodos)

<div data-controller="payment-brick"
     data-payment-brick-public-key-value="<%= payment_method.preferences[:public_key] %>"
     data-payment-brick-amount-value="<%= order.total %>"
     data-payment-brick-email-value="<%= order.email %>"
     data-payment-brick-customer-id-value="<%= customer_id %>"
     data-payment-brick-cards-ids-value="<%= customer_cards_ids %>">
  <div id="paymentBrick_container"></div>
</div>

Card Payment Brick (apenas cartão)

<div data-controller="card-payment-brick"
     data-card-payment-brick-public-key-value="<%= payment_method.preferences[:public_key] %>"
     data-card-payment-brick-amount-value="<%= order.total %>"
     data-card-payment-brick-email-value="<%= order.email %>">
  <div id="cardPaymentBrick_container"></div>
</div>

Autenticação 3D Secure

<div data-controller="three-ds"
     data-three-ds-three-ds-url-value="<%= payment.source.three_ds_url %>"
     data-three-ds-three-ds-creq-value="<%= payment.source.three_ds_creq %>">
</div>

Pagamentos via PIX

O PIX é processado automaticamente. Após a criação do pagamento, o sistema:

  1. Gera o QR Code e código copia e cola
  2. Monitora o status automaticamente
  3. Atualiza o pedido quando o pagamento é confirmado

🗄️ Estrutura do Banco de Dados

Tabelas Criadas

  • solidus_mp_dois_credit_card_sources - Fontes de pagamento por cartão
  • solidus_mp_dois_pix_sources - Fontes de pagamento PIX
  • solidus_mp_dois_customers - Clientes do Mercado Pago
  • solidus_mp_dois_cards - Cartões salvos

Campos Principais

Credit Card Sources

  • external_id - ID do pagamento no Mercado Pago
  • status - Status do pagamento
  • amount - Valor do pagamento
  • installments - Número de parcelas
  • three_ds_url - URL para autenticação 3DS
  • saved_card - Indica se é cartão salvo

PIX Sources

  • external_id - ID do pagamento no Mercado Pago
  • qr_code - Código copia e cola
  • qr_code_base64 - QR Code em base64
  • expiration - Data de expiração
  • ticket_url - URL do ticket de pagamento

🔧 API

Métodos Principais

MpCard

# Criar pagamento
payment = mp_card.create_payment(order, source_params)

# Processar pagamento
response = mp_card.purchase(payment)

# Cancelar pagamento
mp_card.cancel!(payment)

MpPix

# Criar pagamento PIX
payment = mp_pix.create_payment(order)

# Verificar se foi pago
paid = mp_pix.pix_paid?(payment)

# Invalidar pagamento
mp_pix.invalidate_payment(payment)

Sincronização de Status

Os pagamentos são sincronizados automaticamente com o Mercado Pago:

# Buscar status atualizado
mp_payment = payment.source.retrieve_from_api

# Sincronizar manualmente
payment_method.purchase(payment)

🎨 Interface Administrativa

A gem inclui views administrativas completas:

  • Visualização de pagamentos com todos os detalhes
  • QR Codes para pagamentos PIX
  • Informações do cartão (últimos 4 dígitos, bandeira, etc.)
  • Status detalhado e logs de transação

🔒 Segurança

  • ✅ Tokens seguros para cartões
  • ✅ Autenticação 3D Secure automática
  • ✅ Validação de documentos (CPF/CNPJ)
  • ✅ Criptografia end-to-end via Mercado Pago
  • ✅ Logs detalhados para auditoria

🌐 Localização

A gem inclui traduções em português brasileiro:

pt-BR:
  activerecord:
    models:
      solidus_mp_dois/mp_pix: "Pix (Mercado Pago 2)"
      solidus_mp_dois/mp_card: "Cartão de Crédito (Mercado Pago 2)"

🧪 Testes

# Executar todos os testes
bundle exec rake

# Executar testes específicos
bundle exec rspec spec/models/

📋 Dependências

  • solidus_brazilian_adaptations - Adaptações para o mercado brasileiro
  • mp_api - Cliente Ruby para API do Mercado Pago
  • @mercadopago/sdk-js - SDK JavaScript oficial do Mercado Pago