Visão Geral da API

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.

Integrando com IA? (ChatGPT, Claude, Cursor, Copilot)

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.

Formato

JSON UTF-8

Moeda e Valores

Centavos Inteiros (BRL)

Velocidade Média Pix

< 1.2 segundos

Regra de Valores Monetários: Todos os valores na API PrimoPay são sempre expressos em centavos inteiros para evitar inconsistências de arredondamento de ponto flutuante. Por exemplo, para cobrar R$ 149,90, passe o valor 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.

URL Base da APIHTTPS Obrigatório
https://api.primopay.com.br/v1
Ambiente Sandbox (Testes)

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.

Ambiente de Produção (Live)

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

HeaderValor ExemploDescrição
AuthorizationBearer pk_live_4a82b9...Seu Client ID público com prefixo Bearer.
Content-Typeapplication/jsonTipo do corpo de envio (necessário em POST e PUT).
X-Idempotency-Keyord_9841284_v1Chave 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.

200 / 201
Sucesso

A requisição foi processada e os dados solicitados foram retornados.

400
Bad Request

Parâmetros ausentes, JSON malformatado ou validações de negócio falharam.

401
Unauthorized

Chave de API inválida, revogada ou ausente no header Authorization.

404
Not Found

A cobrança, transação ou recurso procurado não foi localizado.

// Exemplo de Resposta de Erro (HTTP 422 Unprocessable Entity)
{
  "error": "O valor da cobrança Pix deve ser de no mínimo R$ 1,00 (100 centavos)",
  "code": "MINIMUM_AMOUNT_REQUIRED",
  "status": 422
}
POST

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/charges

Parâmetros do Body (JSON)

CampoTipoObrigatórioDescrição
amount_centsintegerSimValor da cobrança em centavos (ex: 15000 = R$ 150,00). Mínimo 100.
descriptionstringNãoIdentificador do pedido ou texto exibido na fatura bancária do cliente.
payer_namestringNãoNome do pagador.
payer_documentstringNãoCPF ou CNPJ do pagador (apenas números ou formatado).
expires_in_secondsintegerNãoTempo 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
  }'
Resposta HTTP 201 Createdapplication/json
{
  "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"
}
GET

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
// Exemplo de Resposta quando Paga (HTTP 200 OK)
{
  "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"
}
GET

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=PAID

Parâmetros de Consulta (Query Params)

ParâmetroTipoPadrãoDescrição
pageinteger1Número da página para navegação.
per_pageinteger20Quantidade de registros por página (máx. 100).
statusstring-Filtro por status: PENDING, PAID, EXPIRED ou REFUNDED.
start_date / end_datestring (ISO)-Intervalo de criação das cobranças (ex: 2026-11-01T00:00:00Z).
// Resposta (HTTP 200 OK)
{
  "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
  }
}
POST

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
// Payload opcional de reembolso parcial (se omitido, estorna o valor total)
{
  "amount_cents": 5000,
  "reason": "Cancelamento do pedido pelo cliente"
}
POST

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/simulate
Notificações em Tempo Real

Webhooks & 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

EventoQuando é disparado
pix.charge.paidDisparado no exato instante em que o Pix é liquidado e o saldo é creditado na conta.
pix.charge.refundedDisparado quando uma devolução/estorno de cobrança é confirmada.
pix.charge.expiredDisparado 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.

// Exemplo de Verificação no Node.js / Express
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 });
});
POST

Solicitar Saque Pix

Transfere fundos disponíveis no saldo da sua conta PrimoPay para qualquer chave Pix registrada em seu CPF ou CNPJ.

Segurança Mandatória (Whitelist de IPs): Para proteger seu saldo contra acessos não autorizados, qualquer solicitação de saque através da API requer que o endereço IP do servidor chamador esteja previamente cadastrado na Whitelist de IPs (configurável no painel em Desenvolvedor → Whitelist de IPs para Saques). Requisições originadas de IPs não listados são bloqueadas com HTTP 403 Forbidden.
POST https://api.primopay.com.br/v1/withdrawals
// Request Body
{
  "amount_cents": 50000,
  "pix_key": "financeiro@empresa.com.br",
  "pix_key_type": "EMAIL"
}
GET

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
// Resposta (HTTP 200 OK)
{
  "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.

Obtenha suas credenciais no painel

Copie o Client ID de Sandbox ou Produção e configure seus Webhooks.