Documentação da API PrimoPay
Bem-vindo à documentação oficial da PrimoPay. Nossa API é construída em padrão RESTful, com comunicação estritamente em JSON, respostas estruturadas e códigos de status HTTP padrão. Foi concebida para integração veloz de pagamentos instantâneos via Pix, split de liquidação e webhooks de alta disponibilidade.
Copie o prompt estruturado com todas as especificações da PrimoPay (regras de centavos inteiros, rotas, schemas e validação HMAC) para o seu assistente gerar a integração completa do backend.
JSON UTF-8
Centavos Inteiros (BRL)
< 1.2 segundos
14990. Ambientes & Base URLs
A PrimoPay provê dois ambientes independentes para os usuários: Sandbox (Testes) e Produção (Live). O mesmo endpoint é utilizado, diferenciando-se pelas credenciais autenticadas no cabeçalho.
https://api.primopay.com.br/v1 Utilize chaves iniciadas com pk_test_. As cobranças geradas não debitam dinheiro real e você pode simular o pagamento instantâneo via endpoint de teste.
Utilize chaves iniciadas com pk_live_. Gera QR Codes Pix reais conectados ao Banco Central com liquidação financeira na sua conta PrimoPay.
Autenticação & Chaves de Acesso
As chamadas à API PrimoPay são autenticadas via protocolo HTTP com o esquema padrão Bearer Token ou por headers personalizados. Suas chaves devem ser mantidas em segredo no seu backend e nunca expostas em código front-end (como no navegador ou apps mobiles).
Cabeçalhos Obrigatórios
| Header | Valor Exemplo | Descrição |
|---|---|---|
| Authorization | Bearer pk_live_4a82b9... | Seu Client ID público com prefixo Bearer. |
| Content-Type | application/json | Tipo do corpo de envio (necessário em POST e PUT). |
| X-Idempotency-Key | ord_9841284_v1 | Chave opcional para evitar duplicidade de cobranças. |
Respostas de Erro & Status HTTP
A API PrimoPay utiliza códigos de status HTTP convencionais para indicar o sucesso ou falha das requisições. Erros na faixa 4xx indicam parâmetros inválidos ou falta de autorização, e 5xx indicam falhas internas na infraestrutura.
A requisição foi processada e os dados solicitados foram retornados.
Parâmetros ausentes, JSON malformatado ou validações de negócio falharam.
Chave de API inválida, revogada ou ausente no header Authorization.
A cobrança, transação ou recurso procurado não foi localizado.
{
"error": "O valor da cobrança Pix deve ser de no mínimo R$ 1,00 (100 centavos)",
"code": "MINIMUM_AMOUNT_REQUIRED",
"status": 422
}Criar Cobrança Pix
Gera imediatamente uma nova cobrança Pix dinâmica com QR Code em imagem (Base64) e código Copia e Cola padrão Banco Central pronto para o pagador escanear.
POST https://api.primopay.com.br/v1/chargesParâmetros do Body (JSON)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| amount_cents | integer | Sim | Valor da cobrança em centavos (ex: 15000 = R$ 150,00). Mínimo 100. |
| description | string | Não | Identificador do pedido ou texto exibido na fatura bancária do cliente. |
| payer_name | string | Não | Nome do pagador. |
| payer_document | string | Não | CPF ou CNPJ do pagador (apenas números ou formatado). |
| expires_in_seconds | integer | Não | Tempo de expiração do QR Code em segundos (default: 3600 = 1 hora). |
curl -X POST https://api.primopay.com.br/v1/charges \
-H "Authorization: Bearer pk_live_4a82b9e1..." \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 14990,
"description": "Pedido #4092",
"payer_name": "João da Silva",
"payer_document": "12345678909",
"expires_in_seconds": 3600
}'{
"id": "tx_9a8712ba-4210-4bf0-a912-881c19208a01",
"status": "PENDING",
"amount_cents": 14990,
"description": "Pedido #4092",
"payer_name": "João da Silva",
"payer_document": "123.456.789-09",
"emv_copy_paste": "00020126580014br.gov.bcb.pix0136tx_9a8712ba42104bf0a912881c19208a015204000053039865406149.905802BR5915PRIMOPAY IP S.A6009SAO PAULO62070503***63047A1B",
"qr_code_image_url": "https://api.primopay.com.br/v1/qrcode/tx_9a8712ba-4210.png",
"expires_at": "2026-11-20T20:00:00Z",
"created_at": "2026-11-20T19:00:00Z"
}Consultar Cobrança Pix
Retorna os detalhes completos de uma cobrança específica a partir do seu id único.
GET https://api.primopay.com.br/v1/charges/:id{
"id": "tx_9a8712ba-4210-4bf0-a912-881c19208a01",
"status": "PAID",
"amount_cents": 14990,
"net_amount_cents": 14841,
"fee_cents": 149,
"paid_at": "2026-11-20T19:01:23Z",
"end_to_end_id": "E0003816620261120190123891726a91",
"created_at": "2026-11-20T19:00:00Z"
}Listar Cobranças Pix
Lista as cobranças Pix geradas com filtros por status, datas e paginação flexível.
GET https://api.primopay.com.br/v1/charges?page=1&per_page=20&status=PAIDParâmetros de Consulta (Query Params)
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| page | integer | 1 | Número da página para navegação. |
| per_page | integer | 20 | Quantidade de registros por página (máx. 100). |
| status | string | - | Filtro por status: PENDING, PAID, EXPIRED ou REFUNDED. |
| start_date / end_date | string (ISO) | - | Intervalo de criação das cobranças (ex: 2026-11-01T00:00:00Z). |
{
"charges": [
{
"id": "tx_9a8712ba-4210-4bf0-a912-881c19208a01",
"status": "PAID",
"amount_cents": 14990,
"net_amount_cents": 14841,
"fee_cents": 149,
"paid_at": "2026-11-20T19:01:23Z",
"created_at": "2026-11-20T19:00:00Z"
}
],
"pagination": {
"page": 1,
"per_page": 20,
"total": 142,
"total_pages": 8
}
}Estornar / Reembolso Pix
Efetua a devolução instantânea via Pix dos fundos pagos para a conta bancária de origem do cliente pagador.
POST https://api.primopay.com.br/v1/charges/:id/refund{
"amount_cents": 5000,
"reason": "Cancelamento do pedido pelo cliente"
}Simulador de Pagamento (Apenas Sandbox)
Permite acionar manualmente a liquidação de uma cobrança em ambiente de testes para que seus webhooks recebam o evento de confirmação automaticamente sem precisar ler QR Code.
POST https://api.primopay.com.br/v1/charges/:id/simulateWebhooks & Eventos
Os Webhooks são o método recomendado para você atualizar o status de pedidos no seu sistema em tempo real. Assim que um cliente realiza a leitura e confirma o Pix no banco dele, os servidores da PrimoPay enviam uma requisição HTTP POST para a URL configurada no seu painel.
Eventos Notificados
| Evento | Quando é disparado |
|---|---|
| pix.charge.paid | Disparado no exato instante em que o Pix é liquidado e o saldo é creditado na conta. |
| pix.charge.refunded | Disparado quando uma devolução/estorno de cobrança é confirmada. |
| pix.charge.expired | Disparado quando o tempo de expiração do QR Code é atingido sem pagamento. |
Validação de Assinatura HMAC-SHA256
Cada webhook enviado pela PrimoPay inclui o header X-Signature. Você deve calcular o hash HMAC-SHA256 do corpo bruto (raw body) recebido usando seu Webhook Secret (disponível na página de Desenvolvedor) e conferir se é idêntico ao cabeçalho.
const crypto = require('crypto');
app.post('/webhook-primopay', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const webhookSecret = process.env.PRIMOPAY_WEBHOOK_SECRET;
const expectedSignature = crypto
.createHmac('sha256', webhookSecret)
.update(req.body)
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).send('Assinatura inválida');
}
const event = JSON.parse(req.body.toString());
if (event.event === 'pix.charge.paid') {
const charge = event.data;
console.log(`Pagamento de R$ ${charge.amount_cents / 100} recebido!`);
// Libere o pedido no seu banco de dados
}
// IMPORTANTE: Sempre responda HTTP 200 rapidamente
res.status(200).json({ received: true });
});Solicitar Saque Pix
Transfere fundos disponíveis no saldo da sua conta PrimoPay para qualquer chave Pix registrada em seu CPF ou CNPJ.
HTTP 403 Forbidden. POST https://api.primopay.com.br/v1/withdrawals{
"amount_cents": 50000,
"pix_key": "financeiro@empresa.com.br",
"pix_key_type": "EMAIL"
}Consultar Saldo da Conta
Retorna o saldo disponível para saque imediato e o saldo pendente de liquidação futura.
GET https://api.primopay.com.br/v1/balance{
"balance_available_cents": 1485020,
"balance_pending_cents": 132000,
"currency": "BRL"
}Pronto para Integrar?
Você pode copiar seus exemplos de código diretamente no painel de desenvolvedor com suas chaves de API já preenchidas automaticamente.