Início rápido

Do zero a uma cobrança PIX paga, em minutos.

1. Pegue sua chave de API

No dashboard, em Chaves API, gere uma chave pnk_.... Ela identifica seu tenant — não é preciso enviar tenantId. Detalhes em Autenticação.

2. Crie uma cobrança PIX

curl -X POST 'https://v2.pagnow.com/v1/payments' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "paymentMethods": ["PIX"],
    "idempotencyKey": "pedido-123",
    "customerName": "João Silva",
    "customerDocument": "52998224725",
    "customerEmail": "joao@exemplo.com",
    "webhookUrl": "https://sua-loja.com/webhooks/pagnow"
  }'

A resposta (201) traz o copia-e-cola e o QR para o cliente pagar:

{
  "id": "a99e3d82-352b-49b2-b10e-4551ca69446e",
  "status": "WAITING_PAYMENT",
  "amount": 1990,
  "currency": "BRL",
  "pixCopyPaste": "00020101021226...br.gov.bcb.pix...",
  "pixQrCode": "data:image/png;base64,iVBOR...",
  "pixExpiresAt": "2026-05-27T13:00:00.000Z"
}

Página de checkout hospedada: https://checkout.v2.pagnow.com/{id}.

3. Receba a confirmação

Prefira webhooks a ficar consultando o status. Quando o cliente paga, enviamos um POST assinado para o seu webhookUrl com event: "payment.completed".

Idempotência

Sempre envie idempotencyKey.

Redes falham, requisições dão timeout, jobs re-executam. Se você reenviar a mesma requisição com o mesmo idempotencyKey, a PagNow não cria uma segunda operação — ela retorna a mesma que já existia (mesmo id, mesmo status). Assim você pode repetir com segurança um POST que não sabe se chegou, sem risco de cobrar/pagar duas vezes.

Como usar

• Gere uma chave estável e única para cada operação — normalmente o id do pedido/saque no seu sistema (ex.: "pedido-123", "payout-2026-W17").
• Mesma chave → retorna a mesma operação (idempotente).
• Chave nova → é uma operação nova e distinta.
• Reutilize a chave apenas para reenviar a mesma intenção — nunca para duas operações diferentes.

# Reenviar este POST 3x com o mesmo idempotencyKey cria UMA única cobrança.
curl -X POST 'https://v2.pagnow.com/v1/payments' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{ "amount": 1990, "currency": "BRL", "paymentMethods": ["PIX"], "idempotencyKey": "pedido-123" }'

Saques (payouts) também. Enviar POST /v1/withdrawals com o mesmo idempotencyKey não gera um segundo saque — retorna o saque original. Se você não enviar a chave, ainda há uma proteção automática que bloqueia um saque quase idêntico repetido em poucos segundos — mas o idempotencyKey explícito é a forma correta e recomendada.

Próximos passos

• Criar cobrança PIX (detalhes e exemplos em mais linguagens)
• Consultar status
• Reembolsos e cancelamento
• Webhooks e verificação de assinatura
• SDKs oficiais