# API PagueMax — Documentação Completa Gerado em: 06/09/2026, 21:56:11 --- ## Visão Geral Base URL: http://localhost/api/v1 Autenticação: header `Authorization: Bearer SEU_TOKEN` + header `X-Client-ID: SEU_CLIENT_ID` em todos os requests. Nunca exponha o token no frontend (JS do navegador / mobile). Gere suas credenciais em: Painel → Chave API → Gerar Nova Chave. O token só é exibido uma vez — copie e guarde assim que gerar. --- ## Introdução A API do PagueMax permite que você integre pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples e segura. **Características:** - API RESTful completa - Autenticação via Token Bearer - Webhooks em tempo real - Respostas em JSON --- ## Obter Credenciais de API Para usar a API, você precisa gerar uma chave de API no painel do sistema. **Passo 1: Acesse a página de Chaves de API** No painel do sistema, acesse a seção "Chave API" no menu lateral. **Passo 2: Gere uma nova chave** Clique em "Gerar Nova Chave" e dê um nome descritivo (ex: "Site Principal", "App Mobile"). ⚠️ Importante: Copie e guarde o token imediatamente, pois ele só será exibido uma vez! **Passo 3: Configure no seu sistema** Adicione o token gerado nas configurações do seu site/aplicação. O token terá o formato: ``` nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` --- ## 1. Criar Pagamento PIX (Cash-in) **Endpoint:** POST http://localhost/api/v1/payments/pix ### Parâmetros | Campo | Tipo | Obrigatório | Descrição | |--------------|--------|-------------|-----------------------------------------------| | amount | float | Sim | Valor do pagamento (mínimo: R$ 0,01) | | payer_name | string | Sim | Nome completo do pagador | | payer_email | string | Sim | Email do pagador | | payer_cpf | string | Sim | CPF do pagador (máximo 14 caracteres) | | description | string | Não | Descrição do pagamento | ### Resposta de Sucesso (201) ```json { "success": true, "data": { "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000", "amount": 100.00, "fee": 4.00, "amount_net": 96.00, "status": "pending", "qr_code": "00020126580014BR.GOV.BCB.PIX...", "pix_code": "00020126580014BR.GOV.BCB.PIX...", "expires_at": "2024-11-26T12:30:00Z", "expires_in_seconds": 300 } } ``` ### Exemplo (PHP / Guzzle) ```php post('http://localhost/api/v1/payments/pix', [ 'headers' => [ 'Authorization' => 'Bearer SEU_TOKEN', 'X-Client-ID' => 'SEU_CLIENT_ID', 'Accept' => 'application/json', ], 'json' => [ 'amount' => 100.00, 'payer_name' => 'João Silva', 'payer_email' => 'joao@email.com', 'payer_cpf' => '12345678900', 'description' => 'Pagamento de Teste' ] ]); $body = json_decode($response->getBody(), true); print_r($body); ``` ### Exemplo (Python) ```python import requests url = "http://localhost/api/v1/payments/pix" payload = { "amount": 100.00, "payer_name": "João Silva", "payer_email": "joao@email.com", "payer_cpf": "12345678900", "description": "Pagamento de Teste" } headers = { "Authorization": "Bearer SEU_TOKEN", "X-Client-ID": "SEU_CLIENT_ID", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ### Exemplo (JavaScript / fetch) ```javascript const url = "http://localhost/api/v1/payments/pix"; const payload = { amount: 100.00, payer_name: "João Silva", payer_email: "joao@email.com", payer_cpf: "12345678900", description: "Pagamento de Teste" }; fetch(url, { method: "POST", headers: { "Authorization": "Bearer SEU_TOKEN", "X-Client-ID": "SEU_CLIENT_ID", "Content-Type": "application/json" }, body: JSON.stringify(payload) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error("Error:", error)); ``` ### Exemplo (cURL) ```bash curl -X POST "http://localhost/api/v1/payments/pix" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "X-Client-ID: SEU_CLIENT_ID" \ -H "Content-Type: application/json" \ -d '{ "amount": 100.00, "payer_name": "João Silva", "payer_email": "joao@email.com", "payer_cpf": "12345678900", "description": "Pagamento de Teste" }' ``` --- ## 2. Cashout — Saque via PIX **Endpoint:** POST http://localhost/api/v1/cashout/pix Para saques automáticos funcionarem, você precisa: 1. Configurar o modo de saque como "Automático" ao criar a credencial de API 2. Adicionar o IP do seu servidor nas configurações da API 3. O usuário precisa estar aprovado (KYC) e com saques desbloqueados ### Parâmetros | Campo | Tipo | Obrigatório | Descrição | |----------|--------|-------------|--------------------------------------------------------------------------| | amount | float | Sim | Valor líquido desejado (mínimo: R$ 10,00). O sistema calcula automaticamente o valor bruto incluindo taxas. | | pix_key | string | Sim | Chave PIX de destino (CPF, Email, Telefone ou Chave Aleatória) | ### Resposta de Sucesso ```json { "success": true, "message": "Saque criado e processado automaticamente.", "withdrawal": { "id": 123, "amount": 95.00, "amount_gross": 100.00, "fee": 5.00, "status": "processing", "pix_key": "12345678900" } } ``` --- ## 3. Consultar Transações **Listar:** GET http://localhost/api/v1/transactions **Buscar uma específica:** GET http://localhost/api/v1/transactions/{uuid} ### Parâmetros (query string, todos opcionais) | Campo | Tipo | Descrição | |-------------|---------------------|---------------------------------------------------| | status | string | Filtrar por status (pending, completed, failed, etc) | | type | string | Filtrar por tipo (pix, credit, withdrawal) | | start_date | string (YYYY-MM-DD) | Data inicial do filtro | | end_date | string (YYYY-MM-DD) | Data final do filtro | | per_page | integer | Itens por página (padrão: 20) | ### Resposta de Sucesso ```json { "success": true, "data": [ { "uuid": "550e8400-e29b-41d4-a716-446655440000", "amount_gross": 100.00, "amount_net": 96.00, "fee": 4.00, "type": "pix", "status": "completed", "external_id": "TXN_123456789", "description": "Depósito via PIX - API", "created_at": "2024-01-20T10:30:00Z", "updated_at": "2024-01-20T10:35:00Z" } ], "pagination": { "current_page": 1, "last_page": 5, "per_page": 20, "total": 100 } } ``` --- ## 4. Webhooks (Notificações) Receba notificações automáticas em seu sistema sempre que o status de uma transação mudar. ### Configuração Configure a URL de webhook na sua Chave de API no painel do sistema. 1. Acesse a seção "Chave API" no menu lateral 2. Crie uma nova chave de API ou edite uma existente 3. Preencha o campo "Webhook URL" com a URL do seu servidor 4. Salve as alterações ⚠️ Importante: A URL deve ser pública e acessível via HTTP/HTTPS para receber as notificações. ### Eventos disparados | Evento | Descrição | |-------------------------|---------------------------------------------------------------------| | transaction.completed | Disparado quando o pagamento é confirmado (pago) e o saldo é creditado. | | transaction.failed | Disparado quando o pagamento falha, expira ou é cancelado. | | withdrawal.completed | Disparado quando um saque é completado com sucesso. | ### Payload (POST enviado pra sua URL) ```json { "event": "transaction.completed", "created_at": "2024-01-20T10:30:00Z", "data": { "transaction_id": "550e8400-e29b-41d4-a716-446655440000", "external_id": "TXN_123456789", "amount_gross": 150.00, "amount_net": 145.50, "fee": 4.50, "status": "completed", "paid_at": "2024-01-20T10:35:00Z" } } ``` ### Campos do payload | Campo | Tipo | Descrição | |----------------------|--------------------|-----------------------------------------------| | event | string | Nome do evento disparado | | created_at | string (ISO 8601) | Timestamp de criação do webhook | | data.transaction_id | string (UUID) | UUID único da transação no sistema | | data.external_id | string | ID da transação no gateway externo | | data.amount_gross | float | Valor bruto da transação | | data.amount_net | float | Valor líquido (após taxas) | | data.fee | float | Valor da taxa cobrada | | data.status | string | Status da transação (completed, failed, etc) | | data.paid_at | string (ISO 8601) | Timestamp de confirmação do pagamento | ### Resposta esperada Seu servidor deve responder **HTTP 200 OK** para confirmar o recebimento. Caso contrário, o sistema tentará reenviar a notificação. ### Segurança Para validar que o webhook realmente veio do sistema, você pode: - Verificar o IP de origem (se disponível) - Validar a estrutura do payload - Confirmar o `transaction_id` consultando a API (endpoint de consulta acima) --- ## Códigos de Erro | Código | Significado | Descrição | |--------|------------------------|--------------------------------------------------------------| | 200 | OK | Requisição processada com sucesso. | | 201 | Created | Recurso criado com sucesso (ex: novo pagamento). | | 400 | Bad Request | Dados inválidos enviados na requisição. Verifique os campos. | | 401 | Unauthorized | Token inválido ou não fornecido. | | 403 | Forbidden | Acesso negado ao recurso solicitado. | | 404 | Not Found | Recurso não encontrado (ex: transação inexistente). | | 422 | Unprocessable Entity | Erro de validação (ex: email inválido, saldo insuficiente). | | 500 | Internal Server Error | Erro interno do servidor. Tente novamente mais tarde. | --- *Documentação gerada automaticamente a partir da PagueMax API Reference v1*