The PixGo API allows you to integrate PIX payments into your application quickly and securely. Our RESTful API uses JSON for communication and provides webhooks for real-time notifications.
Key Features:
Instant PIX payment generation
Real-time payment status
Automatic webhook notifications
CPF/CNPJ validation support
Secure API key authentication
Detailed transaction logs
Base URL:
https://pixgo.org/api/v1
Quick Start:
Get your API key, make a POST request to create a payment and receive the PIX QR Code instantly.
Authentication
All API requests require authentication using your API key in the X-API-Key header.
Security: Keep your API Key secure. Never expose it in client-side code or public repositories.
API Endpoints
POST /api/v1/payment/create
Create Payment
Creates a new PIX payment request
MANDATORY FIELD since 06/25/2026
The receiver_cpf field (payer CPF or CNPJ) is MANDATORY on every payment creation, as required by the settlement provider. Charges created without it are rejected.
Ownership lock: once the QR Code is generated, only the informed CPF/CNPJ can pay it. If a third party pays, the payment is automatically rejected and the refund to the third party's account can take up to 48 hours. Make sure the document sent belongs to the person who will actually pay. The field is already available: update your integration now.
Parameters:
{
"amount": 25.50,
"description": "Produto XYZ",
"receiver_name": "João Silva",
"receiver_cpf": "12345678901",
"receiver_email": "joao@exemplo.com",
"receiver_phone": "11999999999",
"receiver_address": "Rua das Flores, 123, Centro, São Paulo, SP, 01234-567",
"external_id": "pedido_123"
}
Validation Rules:
amount: Required. Minimum R$ 10.00, maximum varies by your level
receiver_cpf:Mandatory since 06/25/2026. Payer CPF (11 digits) or CNPJ (14 digits), numbers only, with valid check digit. Only this document will be able to pay the generated QR
receiver_name: Optional (recommended). Payer full name, 2 to 100 characters
receiver_email: Optional. Valid email, maximum 255 characters
receiver_phone: Optional. Phone with area code, 10 or 11 digits, numbers only
receiver_address: Optional. Complete address, 10 to 500 characters
{
"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
Check Payment Status
Retrieves the current status of a payment
Rate Limit:
This endpoint uses your API key's daily quota (10,000 requests per day by default, counting all endpoints). To raise the quota, contact support on Telegram or open a ticket.
About the CPF: the customer_cpf field is returned masked (***.456.789-**). The full document is never returned by the API.
payer_euid: payer identifier at the provider. Comes as null until the payment is confirmed, and may remain null afterwards depending on the provider — do not use this field as a signal that the payment was made; use status for that.
Warning: this endpoint may respond 410
When the payment reaches a final state (expired, canceled, cancelled or refunded), the response comes with HTTP 410 Gone and "terminal": true — the body is identical to the 200 one. Treat 200 and 410 as valid responses; a 410 means "this payment exists and will not change anymore", not an error. These responses also come with Cache-Control: immutable for 24h, so they can be safely cached.
This endpoint does not return customer_cpf. If you need the masked document, use GET /api/v1/payment/{id}/status.
GET /api/v1/payments
Search payments by your external_id
Use this when you only have the external_id you sent at creation and did not store the payment_id. Always returns a list, because external_id is defined by you and may repeat. If yours is unique, just read data[0].
No results: returns 200 with "data": [] and "total": 0 — not 404. A 404 here would mean the URL is wrong, not that the search found nothing.
Payment Status Values:
pending - Awaiting payment
completed - Payment confirmed
expired - Payment expired (see expires_at field)
cancelled - Payment cancelled
Progressive Limit System:
Payment limits evolve through 7 levels based on your confirmed transaction history. Liquid wallet must be validated to use the API. Maximum limit per QR Code: R$ 6,000.00. Each payer CPF/CNPJ has its own daily limit, set by the payment institutions.
Webhooks
Webhooks allow your application to receive automatic real-time notifications when a payment status changes. Configure a webhook URL when creating a payment to receive instant updates.
Configuration
To receive webhooks, include the webhook_url parameter when creating a payment:
payment.expired - Payment expired (see expires_at field)
payment.refunded - Payment refunded
Payload Structure
Update 2026-04: enriched payload with (1) customer form data (customer object), (2) separate PIX payer data (payer object, masked by BCB/LGPD), (3) full fee breakdown and net amount (amounts object), (4) product/checkout data (product object).
How to interpret:customer = data the customer typed in your checkout (name, CPF, phone). Use these for your spreadsheet/CRM. payer = data of who actually paid via PIX (masked by LGPD). May differ from customer (e.g. parent paying for child). amounts.net = net amount you actually receive (after all fees deducted).
Events: payment.expired and payment.refunded
Same structure as payment.completed. The completed_at, expired_at and refunded_at fields indicate which event occurred (only the relevant one is filled).
Each webhook is signed with your Webhook Secret using HMAC-SHA256. The secret is available in the "Checkouts" section of your dashboard, along with your API Key.
How to verify the signature:
Extract the X-Webhook-Timestamp and X-Webhook-Signature from the headers
Concatenate: timestamp + "." + raw JSON request body
Generate the HMAC-SHA256 using your Webhook Secret
Compare with the X-Webhook-Signature header using timing-safe comparison
Where to find:
Your Webhook Secret is available on the Checkouts page of your dashboard, right below your API Key. Never expose the secret in client-side code.
Complete Handler Example (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]);
Tip:
Use the external_id field to easily identify the order in your system when receiving the webhook.
Important:
Always verify the webhook signature before processing data. For critical payments, also make an additional query to the status endpoint to confirm.
Level 1 - Beginner (0 to R$ 299.99 confirmed): Limit of R$ 300.00 per QR Code
Level 2 - Bronze (R$ 300.00 to R$ 499.99 confirmed): Limit of R$ 500.00 per QR Code
Level 3 - Silver (R$ 500.00 to R$ 999.99 confirmed): Limit of R$ 1,000.00 per QR Code
Level 4 - Gold (R$ 1,000.00 to R$ 2,999.99 confirmed): Limit of R$ 1,500.00 per QR Code
Level 5 - Platinum (R$ 3,000.00 to R$ 4,999.99 confirmed): Limit of R$ 2,000.00 per QR Code
Level 6 - Diamond (R$ 5,000.00 to R$ 5,999.99 confirmed): Limit of R$ 2,500.00 per QR Code
Maximum Level - Elite (R$ 6,000.00+ confirmed): Limit of R$ 6,000.00 per QR Code
How Limits Work:
Limits are based on total confirmed payments (status "completed")
Liquid wallet must be validated to use the API
Minimum amount: R$ 10.00 per payment
Daily limit per payer CPF/CNPJ: set by the payment institutions and valid across all receivers
Unlimited QR Codes per day
Automatic evolution based on transaction history
Status Monitoring:
To track payments, query the status endpoint periodically (recommended every 30 seconds).
Payment Expiration:
Each PIX charge has its own expiration window. Always use the expires_at field returned on creation and on payment lookup — do not assume a fixed value.
Important:
All payments are processed in real time in production environment. There is no separate test environment.