🚀 API PaguePix v2 - Documentação de Integração 2026

📋 Informações Gerais

URL Base: https://api.paguepix.com Versão: v2 Protocolo: HTTPS Formato: JSON Autenticação: Basic Auth ou Bearer Token

🔐 Autenticação

Método 1: Basic Authentication (Recomendado)

Authorization: Basic base64(client_id:client_secret)

Método 2: Bearer Token (OAuth)

Authorization: Bearer {access_token}

Exemplo de credenciais:

• Client ID: 20e72d88dea6ac3de27ad4a0be832cc17b58221a
• Client Secret: 8766ccaedaf8372c4da2525f538f6b059688d23e438c941ac80d1138ee3fb985

🎯 Endpoints Disponíveis

1. 🔑 Gerar Token OAuth (Opcional)

Endpoint: POST /v2/oauth/token

Headers:

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials

Resposta de Sucesso (200):

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. 💳 Gerar QR Code PIX

Endpoint: POST /v2/pix/qrcode

Headers:

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

Body:

{
  "amount": 25.50,
  "description": "Pagamento do pedido #123",
  "postback_url": "https://seusite.com/webhook"
}

Resposta de Sucesso (200):

{
  "status": "success",
  "data": {
    "id": "pix_68a394f44fed03.54025351",
    "external_id": "PIX_68A394F188067",
    "amount": 25.50,
    "status": "PENDING",
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "created_at": "2025-08-18T20:44:48Z",
    "expires_at": "2025-08-18T21:44:48Z"
  }
}

Parâmetros:

• amount (obrigatório): Valor do PIX (0.01 a 5000.00)
• description (opcional): Descrição do pagamento
• postback_url (opcional): URL para receber notificações

3. 💰 Consultar Saldo

Endpoint: GET /v2/user/balance

Headers:

Authorization: Bearer {access_token}

Resposta de Sucesso (200):

{
  "statusCode": 200,
  "data": {
    "user_id": 39,
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "balance": 1250.75,
    "cash_in_active": true
  }
}

4. 📊 Listar Transações

Endpoint: GET /v2/user/transactions

Headers:

Authorization: Bearer {access_token}

Parâmetros de Query:

• page (opcional): Página (padrão: 1)
• limit (opcional): Itens por página (1-100, padrão: 20)
• status (opcional): Filtrar por status (PENDING, PAID, CANCELLED)

Resposta de Sucesso (200):

{
  "statusCode": 200,
  "data": {
    "transactions": [
      {
        "id": "PIX_68A394F188067",
        "external_id": "PIX_68A394F188067",
        "amount": 25.50,
        "status": "PAID",
        "type": "pix",
        "description": "PIX QR Code",
        "created_at": "2025-08-18T20:44:48Z",
        "confirmed_date": "2025-08-18T20:45:12Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

🔔 Webhook (Notificações)

Quando um PIX é pago, o sistema enviará uma notificação POST para sua postback_url.

Payload do Webhook:

{
  "transactionType": "RECEIVEPIX",
  "transactionId": "eedf9386640862e6edf7mehlpsqo3dv8",
  "external_id": "PIX_68A394F188067",
  "amount": 25.50,
  "paymentType": "PIX",
  "status": "PAID",
  "dateApproval": "2025-08-18 18:03:20",
  "creditParty": {
    "name": "Cliente PaguePix",
    "email": "cliente@paguepix.com",
    "taxId": "20700534741"
  },
  "debitParty": {
    "bank": "PIXUP SOLUCOES DE PAGAMENTOS LTDA",
    "taxId": "59.667.922/0001-08"
  }
}

Seu endpoint deve:

1. Responder com status HTTP 200
2. Processar o pagamento em seu sistema
3. Validar o external_id para identificar o pedido

📝 Códigos de Erro

Erros de Autenticação (401)

{
  "status": "error",
  "message": "Token inválido ou expirado"
}

Erros de Validação (400)

{
  "status": "error",
  "message": "Valor inválido. O valor deve estar entre R$ 0,01 e R$ 5.000,00"
}

Erros do Servidor (500)

{
  "status": "error",
  "message": "Erro interno do servidor"
}

💻 Exemplos de Código

PHP

<?php
class PaguePixAPI {
    private $baseUrl = 'https://api.paguepix.com';
    private $clientId;
    private $clientSecret;
    
    public function __construct($clientId, $clientSecret) {
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
    }
    
    private function getAuthHeader() {
        return 'Basic ' . base64_encode($this->clientId . ':' . $this->clientSecret);
    }
    
    public function gerarPix($valor, $descricao, $webhookUrl = null) {
        $data = [
            'amount' => $valor,
            'description' => $descricao
        ];
        
        if ($webhookUrl) {
            $data['postback_url'] = $webhookUrl;
        }
        
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . '/v2/pix/qrcode',
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: ' . $this->getAuthHeader(),
                'Content-Type: application/json'
            ]
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            throw new Exception('Erro na API: ' . $response);
        }
        
        return json_decode($response, true);
    }
}

// Exemplo de uso
$api = new PaguePixAPI('seu_client_id', 'seu_client_secret');

try {
    $pix = $api->gerarPix(25.50, 'Pagamento do pedido #123', 'https://seusite.com/webhook');
    echo "PIX criado: " . $pix['data']['external_id'] . "\n";
    echo "QR Code: " . $pix['data']['qr_code'] . "\n";
} catch (Exception $e) {
    echo "Erro: " . $e->getMessage() . "\n";
}
?>

JavaScript (Node.js)

const axios = require('axios');

class PaguePixAPI {
    constructor(clientId, clientSecret) {
        this.baseUrl = 'https://api.paguepix.com';
        this.clientId = clientId;
        this.clientSecret = clientSecret;
    }
    
    getAuthHeader() {
        const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64');
        return `Basic ${credentials}`;
    }
    
    async gerarPix(valor, descricao, webhookUrl = null) {
        const data = {
            amount: valor,
            description: descricao
        };
        
        if (webhookUrl) {
            data.postback_url = webhookUrl;
        }
        
        try {
            const response = await axios.post(`${this.baseUrl}/v2/pix/qrcode`, data, {
                headers: {
                    'Authorization': this.getAuthHeader(),
                    'Content-Type': 'application/json'
                }
            });
            
            return response.data;
        } catch (error) {
            throw new Error(`Erro na API: ${error.response?.data?.message || error.message}`);
        }
    }
}

// Exemplo de uso
const api = new PaguePixAPI('seu_client_id', 'seu_client_secret');

api.gerarPix(25.50, 'Pagamento do pedido #123', 'https://seusite.com/webhook')
    .then(pix => {
        console.log('PIX criado:', pix.data.external_id);
        console.log('QR Code:', pix.data.qr_code);
    })
    .catch(error => {
        console.error('Erro:', error.message);
    });

Python

import requests
import base64
import json

class PaguePixAPI:
    def __init__(self, client_id, client_secret):
        self.base_url = 'https://api.paguepix.com'
        self.client_id = client_id
        self.client_secret = client_secret
    
    def get_auth_header(self):
        credentials = f"{self.client_id}:{self.client_secret}"
        encoded = base64.b64encode(credentials.encode()).decode()
        return f"Basic {encoded}"
    
    def gerar_pix(self, valor, descricao, webhook_url=None):
        url = f"{self.base_url}/v2/pix/qrcode"
        
        headers = {
            'Authorization': self.get_auth_header(),
            'Content-Type': 'application/json'
        }
        
        data = {
            'amount': valor,
            'description': descricao
        }
        
        if webhook_url:
            data['postback_url'] = webhook_url
        
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"Erro na API: {response.text}")

# Exemplo de uso
api = PaguePixAPI('seu_client_id', 'seu_client_secret')

try:
    pix = api.gerar_pix(25.50, 'Pagamento do pedido #123', 'https://seusite.com/webhook')
    print(f"PIX criado: {pix['data']['external_id']}")
    print(f"QR Code: {pix['data']['qr_code']}")
except Exception as e:
    print(f"Erro: {e}")

🛡️ Segurança

✅ Boas Práticas

• Nunca exponha suas credenciais no frontend
• Use HTTPS sempre em produção
• Valide todos os dados recebidos via webhook
• Implemente rate limiting em seu sistema
• Monitore logs de acesso e erros

🔐 Armazenamento Seguro

# Variáveis de ambiente recomendadas
PAGUEPIX_CLIENT_ID=seu_client_id_aqui
PAGUEPIX_CLIENT_SECRET=sua_client_secret_aqui
PAGUEPIX_WEBHOOK_URL=https://seusite.com/webhook

🧪 Ambiente de Testes

Credenciais de Teste

URL: https://api.paguepix.com (mesmo endpoint)
Client ID: test_client_id
Client Secret: test_client_secret

Valores de Teste

• Use valores entre R$ 0,01 e R$ 100,00 para testes
• PIX de teste são automaticamente aprovados após 30 segundos
• Webhooks de teste são enviados normalmente

📞 Suporte

Contato

• Email: suporte@paguepix.com
• WhatsApp: (11) 99999-9999
• Documentação: https://docs.paguepix.com

Status da API

• Uptime: 99.9%
• Monitoramento: https://status.paguepix.com

🔄 Changelog

v2.1 (2026)

• ✅ Webhook com identificação por valor quando external_id é nulo
• ✅ Validação de assinatura flexível
• ✅ Correção de bugs de timezone
• ✅ Melhoria na estabilidade do sistema

v2.0 (2025)

• ✅ Basic Authentication
• ✅ Endpoints RESTful
• ✅ Webhook automático
• ✅ Suporte a OAuth 2.0

© 2026 PaguePix - Todos os direitos reservados