Autenticação

Como autenticar

Envie sua API Key no header X-API-Key em toda requisição:

curl https://api.pagniv.com/v1/balance \
  -H "X-API-Key: sk_live_sua_chave"

Onde gerar sua chave

Acesse Dashboard → Integrações → Chaves de API e clique em Gerar nova chave. A chave completa só é exibida uma vez. Copie e guarde em local seguro.

Ambientes

Boas práticas

• Use variáveis de ambiente para armazenar a chave. Nunca deixe no código-fonte
• Cada ambiente (dev, staging, prod) deve ter sua própria chave
• Revogue chaves comprometidas imediatamente no Dashboard
• Chaves sandbox funcionam apenas em sandbox. Não misture ambientes

# Nunca commite este arquivo
PAGNIV_API_KEY=sk_live_7f3a1b9c4e2d8f6a...

Idempotência

Para evitar duplicidade de cobranças e saques quando há retry de rede ou timeout, envie o header Idempotency-Key com um valor único por operação (UUID v4 é o padrão recomendado):

curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Idempotency-Key: 9b1d3e7c-5f8a-4d2e-9b1d-3e7c5f8a4d2e" \
  -H "Content-Type: application/json" \
  -d '{"amount": 15000, "description": "Pedido #1234"}'

Como funciona

• Se a mesma Idempotency-Key for usada novamente em até 24h, retornamos a resposta original sem reprocessar
• Recomendado em POST /charges e POST /withdrawals
• Use um valor diferente pra cada operação real. Reuso indica retry
• A chave vale dentro da SUA chave de API: ela não colide com a de outro merchant, e continua valendo se a sua integração chamar de outro IP

Idempotency-Key vs externalId

Os dois resolvem problemas diferentes:

• Idempotency-Key (header): protege retries de rede ("não duplique se eu reenviar essa requisição")
• externalId (body, em /charges): identificador do seu pedido no seu sistema ("esse pedido X corresponde a essa cobrança")

Pra integrações robustas, use os dois.

Erros de autenticação