Guia Rápido da API
O essencial para integrar pagamentos Pix instantâneos, saques (Cashout) e emissão de notas fiscais ao seu sistema.
Para acelerar o desenvolvimento com ChatGPT, Claude ou Cursor, baixe nossa documentação técnica estruturada para IAs ou acesse o endpoint /llms.txt.
Base URL da API
https://pay.xingubit.com.brAmbiente de Produção e Sandbox compartilham o mesmo host base, alternando via credenciais do Lojista.
★Como Funciona a sua Conta (Fluxo & Credenciais)
Jornada de Integração Multi-Tenant
Credenciais Xingubit
Você cria sua conta e obtém seu client_id e client_secret no painel.
Ativação Bancária (QQPag)
Com a conta aprovada na QQPag, você salva suas chaves no painel para ativar a liquidação oficial.
Emissão & Webhooks
Seu sistema emite Pix instantâneos via API e recebe confirmações automáticas em tempo real.
1Autenticação na API (OAuth 2.0)
Obtenha um token Bearer JWT de curta duração (1 hora) usando suas credenciais de API:
/v1/oauth/tokencurl -X POST https://pay.xingubit.com.br/v1/oauth/token \ -d "client_id=SEU_CLIENT_ID" \ -d "client_secret=SEU_CLIENT_SECRET"
{
"access_token": "eyJhbGciOiJIUzI1NiIsIn...",
"token_type": "Bearer",
"expires_in": "3600"
}Envie em todas as demais chamadas o header: Authorization: Bearer <token>.
2Múltiplas Aplicações & Credenciais Segregadas
Você pode criar pares de credenciais exclusivos (client_id e client_secret) para cada um dos seus canais de venda (ex: Loja Virtual, PDV Físico, App Mobile). Cada aplicação pode ter seu próprio webhook cadastrado e gera relatórios segregados.
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /v1/applications | Criar nova aplicação com credenciais geradas automaticamente |
| GET | /v1/applications | Listar todas as aplicações ativas da sua conta |
| GET | /v1/applications/{id} | Obter detalhes de uma aplicação específica |
| PUT | /v1/applications/{id} | Atualizar nome ou webhook exclusivo da aplicação |
| POST | /v1/applications/{id}/rotate-secret | Rotacionar imediatamente o Client Secret |
| DELETE | /v1/applications/{id} | Revogar aplicação e invalidar credenciais |
Exemplo em cURL (Criar Aplicação):
curl -X POST https://pay.xingubit.com.br/v1/applications \
-H "Authorization: Bearer SEU_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "E-commerce Shopify",
"webhookUrl": "https://loja.com.br/api/webhooks/pix"
}'3Criar e Gerenciar Cobranças Pix (COB e COBV)
A API suporta duas modalidades de emissão Pix de acordo com as especificações do BACEN: Pix Imediato (COB) para checkouts instantâneos e Pix com Vencimento (COBV) com suporte nativo a juros, multas, descontos e conciliação direta com ERPs via identificadores externos.
/v1/charges1. Pix Imediato (COB)
Checkout / PDVExpiração em 24h. Ideal para e-commerce e pagamentos imediatos no caixa.
{
"paymentMethod": "PIX",
"description": "Pedido #4521 - Loja Virtual",
"amount": { "original": 150.00 },
"payer": {
"name": "Francisco da Silva",
"document": "12345678900"
},
"metadata": {
"externalContractId": "PEDIDO-4521"
}
}2. Pix com Vencimento (COBV)
Faturas / Boleto PixSubstituto do boleto bancário com cálculo diário de juros, multas e baixa automática.
{
"paymentMethod": "PIX",
"description": "Fatura Contrato #8890",
"calendar": {
"dueDate": "2026-08-30",
"validityAfterDue": 30
},
"amount": {
"original": 350.00,
"interest": { "type": "VALOR_DIAS_CORRIDOS", "value": 1.50 },
"fine": { "type": "PERCENTUAL", "value": 2.00 }
},
"payer": {
"name": "Empresa Cliente Ltda",
"document": "12345678000195"
}
}3. Carnê Pix Parcelado
2x a 24xGera um lote de cobranças com vencimentos sequenciais e QR Codes individuais.
{
"paymentMethod": "PIX",
"description": "Venda Parcelada #9901",
"amount": { "original": 600.00 },
"installments": 3,
"installmentIntervalDays": 30,
"calendar": { "dueDate": "2026-09-23" },
"invoice": true,
"invoiceStrategy": "TOTAL_AT_SALE",
"payer": {
"name": "Carlos Souza",
"document": "98765432100"
}
}Resposta da Criação (Comum a ambas as modalidades):
{
"txId": "01915f203b997221a476880628203c94",
"qrCodeImage": "data:image/png;base64,iVBORw0KGgo...",
"qrCodeText": "00020101021226830014br.gov.bcb.pix...",
"pixCopiaECola": "00020101021226830014br.gov.bcb.pix..."
}Operações de Consulta e Cancelamento
| Método | Endpoint | Descrição |
|---|---|---|
| GET | /v1/charges/{txId} | Consulta status da cobrança em tempo real |
| GET | /v1/charges | Listar todas as cobranças emitidas pelo lojista |
| PATCH | /v1/charges/{txId} | Cancelar uma cobrança pendente |
4Receber Webhooks de Pagamento (Guia cURL)
Quando o Pix é pago, nossa fila envia um POST instantâneo para a URL cadastrada na aplicação (ou do lojista) com o payload JSON padronizado:
Exemplo de Notificação Recebida pelo seu Servidor:
POST https://sua-loja.com.br/api/webhooks/pix
Content-Type: application/json
{
"status": "PAID",
"txId": "01915f203b997221a476880628203c94",
"e2eId": "E904008882026082212000001",
"amount": 150.00,
"valor": "150.00",
"paidAt": "2026-08-29T15:14:39.120Z",
"externalContractId": "PEDIDO-4521",
"appId": "0198f123-4567-789a-bcde-f0123456789a",
"metadata": {
"externalContractId": "PEDIDO-4521",
"subscriptionId": "",
"appId": "0198f123-4567-789a-bcde-f0123456789a"
}
}Simule o disparo localmente usando cURL para testar seu endpoint:
curl -X POST https://sua-loja.com.br/api/webhooks/pix \
-H "Content-Type: application/json" \
-d '{
"status": "PAID",
"txId": "01915f203b997221a476880628203c94",
"e2eId": "E904008882026082212000001",
"amount": 150.00,
"valor": "150.00",
"paidAt": "2026-08-29T15:14:39.120Z",
"externalContractId": "PEDIDO-4521",
"appId": "0198f123-4567-789a-bcde-f0123456789a",
"metadata": {
"externalContractId": "PEDIDO-4521",
"subscriptionId": "",
"appId": "0198f123-4567-789a-bcde-f0123456789a"
}
}'5Enviar Pix (Cashout) & Consultar Saldo
Enviar Pix para qualquer chave usando saldo disponível:
{
"pixKey": "12345678900",
"amount": 500.00
}Consultar saldo disponível da sua conta:
{
"available_balance": 14520.00,
"pending_balance": 0.00
}6Gestão de Clientes e Produtos
Gerencie clientes e catálogo fiscal para emissão automática de notas e cobranças recorrentes.
| Módulo | Métodos & Endpoints | Finalidade |
|---|---|---|
| Clientes | POST, GET, PUT, DELETE /v1/customers | CRUD completo de pagadores com CPF/CNPJ e endereço |
| Produtos | POST, GET, PUT, DELETE /v1/products | Cadastro de produtos/serviços com NCM, CFOP e alíquotas |
| GeoCEP | GET /v1/cep/{cep}?numero={n} | Autocompletar endereço e calcular coordenadas fiscais (Requer Bearer Token) |
7Emissão de Notas Fiscais (NF-e, NFS-e, NFCom)
A Xingubit Pay possui motor fiscal unificado para NF-e (mercadorias), NFS-e (serviços) e NFCom (telecomunicações).
Configuração Inicial da Empresa
Operações Fiscais Avulsas
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /v1/invoices/{docType} | Emitir nota avulsa (docType: nfe, nfse, nfcom) |
| GET | /v1/invoices/{docType}/{id} | Consultar status do processamento fiscal |
| GET | /v1/invoices/{docType}/{id}/pdf | Download do DANFE / DANFSE em PDF |
| GET | /v1/invoices/{docType}/{id}/xml | Download do XML assinado e protocolado |
| POST | /v1/invoices/{docType}/{id}/cancelamento | Cancelar nota fiscal autorizada |
| GET | /v1/charges/{id}/invoice/pdf | Download do PDF da NF vinculada a uma cobrança Pix |
8Códigos de Erro & Respostas HTTP
| HTTP | Significado | Ação Recomendada |
|---|---|---|
200 / 201 | Sucesso / Criado | — |
400 | Requisição Inválida | Verifique o corpo e tipos dos campos do JSON |
401 | Token Ausente ou Expirado | Renove o token via /v1/oauth/token |
403 | Acesso Negado | Verifique se o CNPJ/Recurso pertence à sua conta |
404 | Não Encontrado | Verifique o ID ou txId informado |
9Registro de Alterações (Changelog)
Histórico de VersõesHardening de Segurança Web e Conformidade TOP NIC.br (Ceptro.br)
Implementação de cabeçalhos de segurança avançados incluindo Content-Security-Policy (CSP) estrito, Referrer-Policy same-origin, padronização do canal de reporte de vulnerabilidades RFC 9116 (security.txt) e conformidade com os testes de boas práticas da Internet do NIC.br.
Múltiplas Aplicações, Credenciais Segregadas e Webhooks Independentes
Suporte completo à criação de múltiplas aplicações por lojista com credenciais segregadas (Client ID e Secret exclusivos), roteamento de webhooks dedicado por canal de venda (E-commerce, PDV, App Mobile), filtros de cobranças/clientes no Dashboard e gestão completa via API (/v1/applications).
Painel Financeiro de Cobranças Pix, Carnês Parcelados e Modal de QR Code Instantâneo
Transformação completa da tela de Cobranças (/dashboard/charges) com 4 cards de métricas financeiras (Recebido, Pendente, Avulsas e Carnês), abas de status dinâmicas, busca com debounce, modal integrado com QR Code SVG de alta definição, botão de cópia rápida do Pix Copia e Cola e cancelamento seguro de cobranças.
Catálogo LC 116 de Serviços, Atalho Rápido de Cobrança e Auto-Cashout Seguro
Modernização completa de UI/UX das telas de Produtos & Serviços (/dashboard/products) e Saque Pix (/dashboard/cashout), introduzindo catálogo nacional inteligente da LC 116 para NFS-e, atalho [ ⚡ Cobrar Item ] direto para o carrinho e rotina de Saque Automático (Auto-Cashout) com validação estrita de titularidade e testes unitários de segurança.
Suíte de Testes Unitários Automatizados no Frontend (Vitest)
Integração do framework Vitest no Frontend para execução automatizada de testes unitários no pipeline de CI/CD. Cobertura completa dos validadores matemáticos da Receita Federal (CPF/CNPJ Módulo 11), máscaras dinâmicas e utilitários.
Máscaras Dinâmicas em Tempo Real e Validação em Duas Camadas
Implementação de máscaras interativas de formatação automática (CPF/CNPJ dinâmico, Telefone e CEP) e validação em duas camadas: algoritmos matemáticos Módulo 11 da Receita Federal no Frontend e Spring Boot Bean Validation no Backend.
Reformulação de UI/UX da Gestão de Clientes e Ação Rápida de Cobrança
Evolução da tela de Clientes (/dashboard/customers) com busca universal inteligente por Nome/CPF/CNPJ/Email com debounce, cards de métricas da carteira, modal unificado com busca de CEP integrada, atalho '⚡ Cobrar Cliente' e exclusão segura.
Carrinho Multi-Itens, Carnê Pix Parcelado e Emissão Fiscal Híbrida
Adicionado suporte completo a carrinho de múltiplos produtos e serviços, parcelamento em Carnê Pix (2x a 24x com QR Codes individuais) e estratégia fiscal híbrida automática (NFS-e na Prefeitura e NF-e na SEFAZ).
Nova UI/UX para Cobranças: Busca Inteligente de Clientes e Pix CobV Visual
Refatoração completa do formulário de emissão de cobranças com Searchable Combobox de alta escala com debounce, seleção em cards e configuração visual de Pix CobV com juros e vencimento.
Documentação de Pix Imediato (COB) vs CobV e Conciliação ERP
Detalhamento aprofundado na documentação pública e para IAs com comparativo de payloads entre Pix Imediato (COB) e Pix com Vencimento (COBV), enfatizando conciliação automática para ERPs via externalContractId.
Permissões de Assets Estáticos no Container Standalone
Ajuste na cópia e permissões de propriedade (chown nextjs:nodejs) da pasta public/ no Dockerfile standalone para servir favicons e manifestos com alta performance.
Favicons Multi-Resolução e Ícones de Alta Definição
Remoção do favicon padrão do template e geração de pacote completo de favicons com a identidade visual Xingubit Pay (ICO multi-tamanho, PNGs 32px e 180px Apple Touch).
Identidade Visual Customizada, Favicons Vetoriais e Otimização SEO
Implementação de identidade visual moderna do Xingubit Pay com favicons vetoriais em alta resolução, OpenGraph Image dinâmico, Sitemap.xml e Robots.txt automatizados.
Blindagem de Segurança em Endpoints Utilitários de CEP
Proteção com autenticação JWT obrigatória em endpoints de geolocalização e consulta de CEP para prevenção de abuso e ataques DoS.
Padronização de Webhooks, Motor Fiscal Unificado e Gestão de Clientes
Padronização do payload de notificações Webhook, unificação dos endpoints de emissão de NF-e, NFS-e e NFCom via estratégia genérica, e suporte a CRUD de Clientes.
Emissão de Pix CobV e Multi-Tenant QQPag
Introdução do suporte a cobranças com vencimento (CobV) com juros, multas e descontos diretamente integrados à QQPag.
Módulo Fiscal Integrado e Certificados A1
Adicionado suporte a emissão automática de NF-e e NFS-e após confirmação do Pix com upload seguro de Certificado Digital A1.
Integração Acelerada com Inteligência Artificial
Disponibilizamos schemas e exemplos prontos para qualquer agente de IA (ChatGPT, Claude, Cursor, Copilot) implementar sua integração em minutos.