Manual de Uso - API PIX MercadoPago

Requisitos do Sistema

• PHP: Versão 7.2 ou superior (recomendado PHP 8+)
• MySQL: Versão 5.7 ou superior
• Extensão cURL habilitada no PHP
• Extensão PDO habilitada no PHP
• Permissão de escrita na pasta onde a API está hospedada, para salvar os arquivos status_*.json e arquivos de log

1. Visão Geral

Este projeto oferece uma API simplificada para geração de cobranças PIX via MercadoPago, recebimento de notificações de pagamento (webhook), integração com banco de dados MySQL (opcional) e um exemplo de formulário para uso prático e consulta em tempo real.

2. Estrutura dos Arquivos

• config.php - Configurações gerais (token, banco de dados, etc)
• pix_generate.php - Geração de cobranças PIX
• pix_webhook.php - Recebimento de notificações de pagamento
• exemplo_formulario_pix.php - Formulário de exemplo para gerar e acompanhar pagamentos
• banco.sql - Script SQL para criar a tabela de pagamentos
• manual.html - Este manual

3. Configuração Inicial

3.1. Banco de Dados

1. Crie um banco de dados MySQL (ex: pix).
2. Execute o script banco.sql para criar a tabela:

mysql -u root -p pix < banco.sql

3.2. Configuração do Sistema

• Edite o arquivo config.php e preencha:
  • access_token: Seu token do MercadoPago
  • usar_banco: true para usar banco, false para não usar
  • db: Dados de conexão do banco (host, dbname, user, pass, charset)

'db' => [
    'host' => 'localhost',
    'dbname' => 'pix',
    'user' => 'root',
    'pass' => '',
    'charset' => 'utf8mb4'
]

4. Funcionamento dos Arquivos

4.1. config.php

Arquivo central de configuração. Define token do MercadoPago, se o banco será usado e os dados de conexão do banco.

4.2. pix_generate.php

• Recebe dados via POST (nome, cpf, valor, descricao).
• Gera uma cobrança PIX via API MercadoPago.
• Retorna um JSON com id, qrcode (base64), copiaecola e status.
• Se banco habilitado, salva os dados do pagamento na tabela pagamentos_pix (sem dados de retorno ainda).

4.3. pix_webhook.php

• Recebe notificações do MercadoPago (webhook HTTP POST).
• Consulta o status do pagamento na API MercadoPago.
• Salva o JSON de retorno em status_ID.json.
• Se banco habilitado, atualiza o registro do pagamento com status, dados de retorno e campo recebido (1 para aprovado, 0 para não).

4.4. exemplo_formulario_pix.php

• Formulário HTML para enviar nome, cpf, valor e descricao para pix_generate.php via AJAX.
• Exibe o QRCode e linha "copia e cola" ao gerar o Pix.
• Mostra um timer de expiração do QRCode.
• Faz polling automático (AJAX) para verificar o status do pagamento em tempo real, exibindo "Pagamento concluído!" quando aprovado.

4.5. banco.sql

• Script SQL para criar a tabela pagamentos_pix no banco de dados.

5. Como Usar

5.1. Gerar um Pix

1. Acesse exemplo_formulario_pix.php no navegador.
2. Preencha os campos: Nome, CPF, Valor, Descrição.
3. Clique em "Gerar PIX".
4. O QRCode e a linha "copia e cola" aparecerão na tela.

5.2. Pagamento em Tempo Real

• Após gerar o Pix, o sistema começa a consultar automaticamente o status do pagamento.
• Quando o pagamento for aprovado, aparecerá a mensagem Pagamento concluído! sem precisar atualizar a página.

5.3. Integração Manual (API)

• Envie um POST para pix_generate.php com os campos:
  • nome
  • cpf
  • valor
  • descricao (opcional)
• Receba um JSON com os dados do Pix.
• Para acompanhar o status, consulte periodicamente o arquivo status_ID.json (onde ID é o id do pagamento retornado).

POST /APIS/pixmercpago/pix_generate.php
Content-Type: application/x-www-form-urlencoded

nome=Joao+Silva&cpf=12345678901&valor=10.00&descricao=Teste+Pix

5.4. Webhook

• No painel do MercadoPago, configure o webhook para apontar para pix_webhook.php.
• O webhook é responsável por atualizar o status do pagamento no banco e no arquivo JSON.

6. Observações Importantes

• Nunca compartilhe seu access_token publicamente.
• O campo recebido no banco indica se o pagamento foi aprovado (1) ou não (0).
• O sistema funciona mesmo sem banco de dados, basta definir usar_banco como false no config.php.
• Os arquivos de status (status_ID.json) são criados pelo webhook e usados para consulta em tempo real.
• Para produção, desative a exibição de erros PHP.

7. Suporte e Dúvidas

Em caso de dúvidas, consulte os arquivos de log (erro_pix_generate.log, erro_db.log) ou revise as configurações do config.php e do banco de dados.