Documentação da API PixGo: cobranças Pix e webhooks

Introdução

A PixGo API permite integrar pagamentos PIX em sua aplicação de forma rápida e segura. Nossa API RESTful utiliza JSON para comunicação e oferece webhooks para notificações em tempo real.

Principais Recursos:

Geração instantânea de pagamentos PIX
Status de pagamento em tempo real
Notificações automáticas via webhook
Suporte à validação de CPF/CNPJ
Autenticação segura via API key
Logs detalhados de transações

URL Base:

https://pixgo.org/api/v1

Início Rápido: Obtenha sua API key, faça uma requisição POST para criar um pagamento e receba o QR Code PIX instantaneamente.

Autenticação

Todas as requisições da API requerem autenticação usando sua chave de API no header X-API-Key.

Obtendo sua API Key:

Crie uma conta em pixgo.org
Valide suas informações de carteira Liquid
Acesse a seção "Checkouts"
Gere sua chave de API

Exemplo de Header:

X-API-Key: pk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Segurança: Mantenha sua API Key segura. Nunca a exponha em código client-side ou repositórios públicos.

Endpoints da API

POST /api/v1/payment/create

Criar Pagamento

Cria uma nova solicitação de pagamento PIX

CAMPO OBRIGATÓRIO desde 25/06/2026

O campo receiver_cpf (CPF ou CNPJ de quem vai pagar) é OBRIGATÓRIO em toda criação de pagamento, por exigência do provedor de liquidação. Cobranças criadas sem ele são recusadas.

Trava de titularidade: a partir da geração do QR Code, somente o CPF/CNPJ informado pode pagá-lo. Se um terceiro pagar, o pagamento é rejeitado automaticamente e o estorno para a conta do terceiro pode levar até 48 horas. Garanta que o documento enviado é o de quem realmente vai pagar. O campo já está disponível: ajuste sua integração desde já.

Parâmetros:

{ "amount": 25.50, "description": "Produto XYZ", "receiver_name": "João Silva", "receiver_cpf": "12345678901", "receiver_email": "[email protected]", "receiver_phone": "11999999999", "receiver_address": "Rua das Flores, 123, Centro, São Paulo, SP, 01234-567", "external_id": "pedido_123" }

Regras de Validação:

amount: Obrigatório. Mínimo R$ 10,00, máximo varia conforme seu nível
receiver_cpf: Obrigatório desde 25/06/2026. CPF (11 dígitos) ou CNPJ (14 dígitos) de quem vai pagar, apenas números, com dígito verificador válido. Só esse documento poderá pagar o QR gerado
receiver_name: Opcional (recomendado). Nome completo do pagador, 2 a 100 caracteres
receiver_email: Opcional. Email válido, máximo 255 caracteres
receiver_phone: Opcional. Telefone com DDD, 10 ou 11 dígitos, apenas números
receiver_address: Opcional. Endereço completo, 10 a 500 caracteres
external_id: Opcional. Máximo 50 caracteres
description: Opcional. Máximo 200 caracteres

Resposta de Sucesso: (201)

{
  "success": true,
  "data": {
    "payment_id": "dep_1234567890abcdef",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_image_url": "https://pixgo.org/qr/dep_1234567890abcdef.png",
    "expires_at": "2025-01-15T12:20:00",
    "created_at": "2025-01-15T12:00:00"
  }
}

Resposta de Erro: (400)

{
  "success": false,
  "error": "LIMIT_EXCEEDED",
  "message": "Valor excede seu limite atual de R$ 300,00",
  "current_limit": 300.00,
  "amount_requested": 500.00
}

GET /api/v1/payment/{id}/status

Consultar Status

Obtém o status atual de um pagamento

Limite de Requisições: Este endpoint tem um limite de 1.000 requisições por 24 horas. Caso precise aumentar esse limite, entre em contato com o suporte via email ou pelo grupo do Telegram (botão disponível no dashboard da PixGo).

Resposta de Sucesso: (200)

{
  "success": true,
  "data": {
    "payment_id": "dep_1234567890abcdef",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "completed",
    "customer_name": "João Silva",
    "customer_cpf": "***.456.789-**",
    "payer_euid": null,
    "customer_phone": "(11) 99999-9999",
    "created_at": "2025-01-15T12:00:00",
    "updated_at": "2025-01-15T12:15:30"
  }
}

Sobre o CPF: o campo customer_cpf é retornado mascarado (***.456.789-**). O documento completo nunca é devolvido pela API.

payer_euid: identificador do pagador no provedor. Vem null enquanto o pagamento não for confirmado, e pode continuar null mesmo depois, dependendo do provedor — não use este campo como sinal de que o pagamento foi pago; para isso use status.

GET /api/v1/payment/{id}

Detalhes do Pagamento

Obtém informações completas do pagamento

Resposta de Sucesso: (200)

{
  "success": true,
  "terminal": false,
  "data": {
    "payment_id": "dep_1234567890abcdef",
    "external_id": "pedido_123",
    "amount": 25.50,
    "status": "completed",
    "customer_name": "João Silva",
    "customer_phone": "(11) 99999-9999",
    "customer_address": "Rua das Flores, 123, Centro, São Paulo, SP, 01234-567",
    "description": "Produto XYZ",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "qr_image_url": "https://pixgo.org/qr/dep_1234567890abcdef.png",
    "created_at": "2025-01-15T12:00:00",
    "updated_at": "2025-01-15T12:15:30",
    "expires_at": "2025-01-15T12:20:00"
  }
}

Atenção: este endpoint pode responder 410
Quando o pagamento chega a um estado final (expired, canceled, cancelled ou refunded), a resposta vem com HTTP 410 Gone e "terminal": true — o corpo é idêntico ao do 200. Trate 200 e 410 como respostas válidas; um 410 significa "este pagamento existe e não muda mais", não erro. Essas respostas também vêm com Cache-Control: immutable por 24h, então podem ser cacheadas com segurança.

Este endpoint não retorna customer_cpf. Se precisar do documento mascarado, use GET /api/v1/payment/{id}/status.

GET /api/v1/payments

Buscar pagamentos pelo seu external_id

Use quando você tem apenas o external_id que enviou na criação e não guardou o payment_id. Retorna sempre uma lista, porque o external_id é definido por você e pode se repetir. Se o seu for único, basta ler data[0].

Parâmetros (query string)

external_id: Obrigatório. Máximo 50 caracteres
limit: Opcional. Padrão 20, máximo 100
offset: Opcional. Padrão 0

curl -H "X-API-Key: SUA_CHAVE" \
  "https://pixgo.org/api/v1/payments?external_id=pedido_123"

Resposta de Sucesso: (200)

{
  "success": true,
  "count": 1,
  "total": 1,
  "limit": 20,
  "offset": 0,
  "data": [
    {
      "payment_id": "dep_1234567890abcdef",
      "external_id": "pedido_123",
      "amount": 25.50,
      "status": "completed",
      "terminal": false,
      "customer_name": "João Silva",
      "customer_phone": "(11) 99999-9999",
      "customer_address": "Rua das Flores, 123, Centro, São Paulo, SP, 01234-567",
      "description": "Produto XYZ",
      "qr_code": "00020126580014BR.GOV.BCB.PIX...",
      "qr_image_url": "https://pixgo.org/qr/dep_1234567890abcdef.png",
      "created_at": "2025-01-15T12:00:00",
      "updated_at": "2025-01-15T12:15:30",
      "expires_at": "2025-01-15T12:20:00"
    }
  ]
}

Nenhum resultado: retorna 200 com "data": [] e "total": 0 — não 404. Um 404 aqui significaria que a URL está errada, não que a busca não encontrou nada.

Status de Pagamento:

pending - Aguardando pagamento
completed - Pagamento confirmado
expired - Pagamento expirado (ver campo expires_at)
cancelled - Pagamento cancelado

Sistema de Progressão de Limites: Os limites de pagamento evoluem em 7 níveis conforme seu histórico de transações confirmadas. Carteira Liquid deve estar validada para usar a API. Limite máximo por QR Code: R$ 6.000,00. Limite diário por CPF/CNPJ pagador: R$ 6.000,00.

Webhooks

Os webhooks permitem que sua aplicação receba notificações automáticas em tempo real quando o status de um pagamento muda. Configure uma URL de webhook ao criar um pagamento para receber atualizações instantâneas.

Configuração

Para receber webhooks, inclua o parâmetro webhook_url ao criar um pagamento:

{
  "amount": 25.50,
  "description": "Produto XYZ",
  "receiver_cpf": "12345678901",
  "webhook_url": "https://seusite.com/webhook/pixgo"
}

Requisitos do Endpoint

Seu endpoint deve aceitar requisições POST
Responda com HTTP 200-299 para confirmar recebimento
Timeout: 10 segundos por tentativa
Recomendamos usar HTTPS para segurança

Eventos Disponíveis

payment.completed - Pagamento confirmado com sucesso
payment.expired - Pagamento expirado (ver campo expires_at)
payment.refunded - Pagamento reembolsado

Estrutura do Payload

Atualização 2026-04: payload enriquecido com (1) dados do cliente que preencheu o checkout (objeto customer), (2) dados do pagador PIX separados (objeto payer — vem mascarado por LGPD do BCB), (3) breakdown completo de taxas e valor líquido (objeto amounts), (4) dados do produto/checkout (objeto product).

Evento: payment.completed

{ "event": "payment.completed", "timestamp": "2026-04-14T12:15:30-03:00", "data": { "payment_id": "019d8d01af2f7015b490df4f04a40956", "external_id": "checkout_313f69e00bec13ba34470bb6b8e46c2c_17761871", "checkout_id": "313f69e00bec13ba34470bb6b8e46c2c", "status": "completed", "description": "X-Frango Premium", "customer": { "name": "Marcos Lins", "cpf": "37933480837", "email": "[email protected]", "phone": "(14) 97515-3504", "address": "Rua Exemplo, 123", "custom_field": { "label": "Apartamento", "value": "205-B" } }, "payer": { "name": "CLEITON HENRIQUE GONCALVES", "cpf": "***.334.808-**" }, "product": { "business_name": "PhedeXs Strategies", "description": "X-Frango Premium: Delicioso e Completo!", "value": 10.00 }, "amount": 10.00, "amounts": { "gross": 10.00, "fee_pixgo": 1.20, "fee_liquid": 0.50, "fee_total": 1.70, "net": 8.30, "currency": "BRL" }, "created_at": "2026-04-14 12:00:00", "updated_at": "2026-04-14 12:15:30", "completed_at": "2026-04-14 12:15:30", "expired_at": null, "refunded_at": null } }

Como interpretar: customer = dados que o cliente digitou no seu checkout (nome, CPF, telefone). Use estes para sua planilha/CRM.
payer = dados de quem efetivamente pagou via PIX (vem mascarado por LGPD). Pode ser diferente do customer (ex: pai pagando boleto do filho).
amounts.net = valor líquido que você efetivamente recebe (já descontadas todas as taxas).

Eventos: payment.expired e payment.refunded

Mesma estrutura do payment.completed. Os campos completed_at, expired_at e refunded_at indicam qual evento ocorreu (apenas o relevante é preenchido).

Headers da Requisição

Cada webhook enviado inclui os seguintes headers:

Content-Type: application/json
X-Webhook-Event: payment.completed
X-Webhook-Timestamp: 1705328130
X-Webhook-Signature: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
User-Agent: PixGo-Webhook/1.0

Verificação de Assinatura (Webhook Secret)

Cada webhook é assinado com seu Webhook Secret usando HMAC-SHA256. O secret está disponível na seção "Checkouts" do seu dashboard, junto com sua API Key.

Como verificar a assinatura:

Extraia o X-Webhook-Timestamp e o X-Webhook-Signature dos headers
Concatene: timestamp + "." + body JSON bruto da requisição
Gere o HMAC-SHA256 usando seu Webhook Secret
Compare com o header X-Webhook-Signature de forma timing-safe

Exemplo de Verificação (PHP):

$webhookSecret = 'whsec_seu_webhook_secret_aqui'; $payload = file_get_contents('php://input'); $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? ''; $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; // Gerar assinatura esperada $signaturePayload = $timestamp . '.' . $payload; $expectedSignature = hash_hmac('sha256', $signaturePayload, $webhookSecret); // Comparar de forma segura (timing-safe) if (!hash_equals($expectedSignature, $signature)) { http_response_code(401); exit('Assinatura invalida'); } // Opcional: rejeitar timestamps antigos (protecao contra replay attack) if (abs(time() - intval($timestamp)) > 300) { http_response_code(401); exit('Timestamp expirado'); } // Assinatura valida - processar webhook normalmente $data = json_decode($payload, true);

Exemplo de Verificação (Node.js):

Onde encontrar: Seu Webhook Secret está disponível na página de Checkouts do dashboard, logo abaixo da sua API Key. Nunca exponha o secret em código client-side.

Exemplo Completo de Handler (PHP)

<?php $webhookSecret = 'whsec_seu_webhook_secret_aqui'; // Receber dados do webhook $payload = file_get_contents('php://input'); $timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? ''; $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; // Verificar assinatura $expected = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret); if (!hash_equals($expected, $signature)) { http_response_code(401); exit('Assinatura invalida'); } $data = json_decode($payload, true); // Validar se é um evento válido if (!$data || !isset($data['event'])) { http_response_code(400); exit('Invalid payload'); } // Processar evento switch ($data['event']) { case 'payment.completed': $paymentId = $data['data']['payment_id']; $amountGross = $data['data']['amounts']['gross']; // valor bruto pago $amountNet = $data['data']['amounts']['net']; // valor líquido recebido $customerName = $data['data']['customer']['name']; // nome do cliente do checkout $customerCpf = $data['data']['customer']['cpf']; // CPF do cliente $payerName = $data['data']['payer']['name']; // nome do pagador PIX (BCB) $payerCpf = $data['data']['payer']['cpf']; // CPF mascarado por LGPD // Atualizar seu banco de dados // marcarPedidoComoPago($data['data']['external_id']); // Enviar email de confirmação // enviarEmailConfirmacao($data['data']); error_log("Pagamento {$paymentId} confirmado: R$ {$amount} de {$payerName}"); break; case 'payment.expired': $paymentId = $data['data']['payment_id']; // Cancelar pedido // cancelarPedido($data['data']['external_id']); error_log("Pagamento {$paymentId} expirou"); break; } // Responder com sucesso http_response_code(200); echo json_encode(['received' => true]);

Dica: Utilize o campo external_id para identificar facilmente o pedido no seu sistema quando receber o webhook.

Importante: Sempre verifique a assinatura do webhook antes de processar os dados. Para pagamentos críticos, faça também uma consulta adicional ao endpoint de status para confirmar.

Exemplos de Código

Exemplo PHP:

<?php $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => 'https://pixgo.org/api/v1/payment/create', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'X-API-Key: pk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' ], CURLOPT_POSTFIELDS => json_encode([ 'amount' => 25.50, 'description' => 'Produto XYZ', 'customer_name' => 'João Silva', 'customer_cpf' => '12345678901', 'customer_email' => '[email protected]', 'customer_phone' => '(11) 99999-9999', 'customer_address' => 'Rua das Flores, 123, Centro, São Paulo, SP, 01234-567', 'external_id' => 'pedido_123' ]) ]); $response = curl_exec($curl); $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($httpCode === 201) { $data = json_decode($response, true); echo "Pagamento criado: " . $data['data']['payment_id']; echo "QR Code URL: " . $data['data']['qr_image_url']; } else { echo "Erro: " . $response; }

Exemplo JavaScript:

const axios = require('axios'); async function createPayment() { try { const response = await axios.post('https://pixgo.org/api/v1/payment/create', { amount: 25.50, description: 'Produto XYZ', customer_name: 'João Silva', customer_cpf: '12345678901', customer_email: '[email protected]', customer_phone: '(11) 99999-9999', customer_address: 'Rua das Flores, 123, Centro, São Paulo, SP, 01234-567', external_id: 'pedido_123' }, { headers: { 'Content-Type': 'application/json', 'X-API-Key': 'pk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' } }); console.log('Pagamento criado:', response.data.data.payment_id); console.log('QR Code URL:', response.data.data.qr_image_url); return response.data; } catch (error) { console.error('Erro:', error.response?.data || error.message); } } createPayment();

Consultar Status (PHP):

function checkPaymentStatus($paymentId) {
    $curl = curl_init();
    
    curl_setopt_array($curl, [
        CURLOPT_URL => "https://pixgo.org/api/v1/payment/{$paymentId}/status",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: pk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
        ]
    ]);
    
    $response = curl_exec($curl);
    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    
    if ($httpCode === 200) {
        $data = json_decode($response, true);
        return $data['data']['status'];
    }
    
    return false;
}

// Uso
$status = checkPaymentStatus('dep_1234567890abcdef');
echo "Status do pagamento: " . $status;

Primeiros Passos

Siga estes passos para começar a usar a PixGo API:

Processo de Cadastro:

Acesse pixgo.org e crie sua conta
Valide suas informações de carteira Liquid
Navegue até a seção "Checkouts"
Gere sua API Key de produção
Comece a integrar pagamentos PIX

Chaves de API:

Todas as chaves de API são para uso em produção - não há ambiente de teste separado

pk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Sistema de Progressão - 7 Níveis:

Nível 1 - Iniciante (0 a R$ 299,99 confirmados): Limite de R$ 300,00 por QR Code
Nível 2 - Bronze (R$ 300,00 a R$ 499,99 confirmados): Limite de R$ 500,00 por QR Code
Nível 3 - Prata (R$ 500,00 a R$ 999,99 confirmados): Limite de R$ 1.000,00 por QR Code
Nível 4 - Ouro (R$ 1.000,00 a R$ 2.999,99 confirmados): Limite de R$ 1.500,00 por QR Code
Nível 5 - Platina (R$ 3.000,00 a R$ 4.999,99 confirmados): Limite de R$ 2.000,00 por QR Code
Nível 6 - Diamante (R$ 5.000,00 a R$ 5.999,99 confirmados): Limite de R$ 2.500,00 por QR Code
Nível Máximo - Elite (R$ 6.000,00+ confirmados): Limite de R$ 6.000,00 por QR Code

Como Funcionam os Limites:

Os limites são baseados no total de pagamentos confirmados (status "completed")
Carteira Liquid deve estar validada para usar a API
Valor mínimo: R$ 10,00 por pagamento
Limite diário por CPF/CNPJ pagador: R$ 6.000,00
Quantidade ilimitada de QR Codes por dia
Evolução automática conforme histórico de transações

Monitoramento de Status:

Para acompanhar pagamentos, consulte o endpoint de status periodicamente (recomendado a cada 30 segundos).

Expiração de Pagamentos:

Cada cobrança PIX tem seu próprio prazo de expiração. Use sempre o campo expires_at devolvido na criação e na consulta do pagamento — não assuma um valor fixo.

Importante: Todos os pagamentos são processados em tempo real em ambiente de produção. Não existe ambiente de teste separado.

Suporte

Precisa de ajuda? Entre em contato com nossa equipe:

Email: [email protected]
Telegram: Acesse o grupo de suporte através do botão disponível no dashboard da PixGo
Documentação: Sempre atualizada nesta página

Recursos Adicionais:

Documentação sempre atualizada nesta página
Suporte técnico via email e Telegram para desenvolvedores
Solicitação de aumento de limites de API disponível

Documentação API PixGo

Introdução

Principais Recursos:

URL Base:

Autenticação

Obtendo sua API Key:

Exemplo de Header:

Endpoints da API

POST /api/v1/payment/create

Criar Pagamento

Parâmetros:

Resposta de Sucesso: (201)

Resposta de Erro: (400)

GET /api/v1/payment/{id}/status

Consultar Status

Resposta de Sucesso: (200)

GET /api/v1/payment/{id}

Detalhes do Pagamento

Resposta de Sucesso: (200)

GET /api/v1/payments

Buscar pagamentos pelo seu external_id

Parâmetros (query string)

Resposta de Sucesso: (200)

Status de Pagamento:

Webhooks

Configuração

Requisitos do Endpoint

Eventos Disponíveis

Estrutura do Payload

Evento: payment.completed

Eventos: payment.expired e payment.refunded

Headers da Requisição

Verificação de Assinatura (Webhook Secret)

Como verificar a assinatura:

Exemplo de Verificação (PHP):

Exemplo de Verificação (Node.js):

Exemplo Completo de Handler (PHP)

Exemplos de Código

Exemplo PHP:

Exemplo JavaScript:

Consultar Status (PHP):

Primeiros Passos

Processo de Cadastro:

Chaves de API:

Sistema de Progressão - 7 Níveis:

Monitoramento de Status:

Expiração de Pagamentos:

Suporte