Comece aqui

Este guia leva você da primeira chave até a primeira cobrança paga. Comece no sandbox. Nada aqui cobra dinheiro real até você trocar a chave para produção.

O cockpit é https://app.pgz.link. A API é https://api.pgz.link.

1. Crie a chave de API

No cockpit, abra Configurações → Integrações. No topo à direita, deixe o seletor de ambiente em Sandbox.

Em Chave de API, preencha Nome da chave (por exemplo, "Backend de teste") e clique em Gerar chave.

A chave começa com pgz_test_ no sandbox e pgz_live_ em produção.

A chave aparece uma vez só

A chave em claro é mostrada apenas no momento da criação. Guarde-a num lugar seguro. Se você perder a chave, não há como recuperá-la — gere uma nova e apague a antiga.

O que existe e o que não existe:

Revogar: sim. O botão de lixeira revoga a chave. Ela deixa de funcionar na hora.
Rotacionar: não existe. Para trocar uma chave, gere uma nova e revogue a antiga.
Escopos: você não escolhe. Toda chave criada no cockpit recebe acesso completo à API.

2. Test e live: test nunca cobra

Cada chave pertence a um ambiente, e os dois são isolados.

Uma chave pgz_test_ nunca alcança o provedor de pagamento e nunca gera cobrança real.
Uma chave pgz_live_ opera em produção.

Recursos criados num ambiente são invisíveis no outro.

Produção usa dinheiro real

Ao criar chaves em Live, o cockpit avisa: "Chaves de produção criam cobranças com dinheiro real." Comece sempre no sandbox.

3. Onde pôr a chave

A chave vai no header Authorization, no formato Bearer:

Authorization: Bearer pgz_test_...

4. Sua primeira chamada: crie uma cobrança

Este comando cria um payment link de R$ 2.500,00. Troque a chave pela sua.

bash

curl https://api.pgz.link/v1/payment_links \
  -H "Authorization: Bearer pgz_test_..." \
  -H "Idempotency-Key: 3f1a9b2c-6d4e-4a71-9c2f-8e5b1d0a7c33" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 250000, "currency": "BRL", "reference": "pedido-8842" }'

Você recebe:

json

{
  "id": "pl_9f8c...",
  "checkout_url": "https://sualoja.pgz.link/pay/pl_9f8c...",
  "reference": "pedido-8842",
  "status": "active"
}

amount: 250000 são R$ 2.500,00 (valor em centavos).
reference é a sua chave de conciliação. Ela volta em toda leitura e em todo webhook. Use o número do seu pedido.
O header Idempotency-Key protege contra cobrança duplicada: se a mesma requisição chegar duas vezes (uma falha de rede, um retry), a segunda devolve a resposta da primeira em vez de criar outra cobrança. Use uma string única por requisição — recomendamos um UUID.

O checkout_url fica em sualoja.pgz.link. Aqui, sualoja é o slug da sua loja — o identificador que você define no cockpit. Com domínio próprio (passo 9), esse endereço vira o seu.

Pegue o checkout_url e envie ao seu cliente. Ele paga nessa página.

O caminho principal é PIX. Cartão de crédito também existe, com parcelamento — os detalhes estão na Referência.

5. Cadastre o webhook, gere o secret e verifique a assinatura

O webhook é como você fica sabendo que o pagamento foi confirmado.

Em Configurações → Integrações → Webhook, preencha URL de webhook com o endereço do seu servidor e clique em Salvar URL. Depois clique em Gerar secret.

O secret aparece uma vez só

O secret de assinatura é mostrado apenas quando você o gera. Guarde-o. Para trocá-lo, use Rotacionar secret — o novo valor também aparece só uma vez.

A cada evento, a plataforma faz um POST na sua URL com este header:

Pagooz-Signature: t=1700000000,v1=<hex>

Para verificar: calcule o HMAC-SHA256 do texto "{t}.{body}" usando o seu secret, e compare com o valor v1. Rejeite entregas em que t esteja a mais de 5 minutos do horário atual.

const crypto = require("crypto");

function verifyPagoozSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // 5 min
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Os eventos que você recebe: payment.succeeded, payment.failed e payment.cancelled.

Sempre responda 2xx

A entrega só é considerada bem-sucedida com uma resposta 2xx. Uma falha aciona novas tentativas com espera crescente. O mesmo evento pode chegar mais de uma vez — processe cada event.id uma única vez.

6. Simule um pagamento no sandbox

No sandbox você fecha o ciclo sem gastar dinheiro. Simule o resultado de um link de teste:

bash

curl https://api.pgz.link/v1/payment_links/pl_9f8c.../simulate_payment \
  -H "Authorization: Bearer pgz_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "succeeded" }'

Isso move o pagamento para o estado pedido e dispara o webhook correspondente, assinado do mesmo jeito que em produção. Valores de outcome: succeeded, failed, expired.

Este endpoint só existe no sandbox. Com uma chave pgz_live_, ele retorna 403.

7. Como saber que funcionou

Duas formas:

Seu webhook. Ele recebeu payment.succeeded para o reference certo? Essa é a fonte da verdade.
O painel "Últimas entregas" no cockpit (em Integrações). Ele mostra as últimas entregas de webhook: o evento, quando, o status e o número de tentativas. Um botão Atualizar recarrega a lista.

"Últimas entregas" não mostra o corpo da resposta

O painel mostra evento, horário, status e tentativas. Ele não mostra o corpo da resposta do seu servidor nem o payload enviado. Para depurar o conteúdo, registre a requisição do seu lado.

Não há endpoint de consulta de eventos

A entrega dos eventos é pelo webhook. Não existe um endpoint da API para listar ou buscar eventos passados. Se o seu servidor pode ficar fora do ar, guarde os webhooks que recebe.

8. Passe para produção

Quando o fluxo funcionar no sandbox:

No cockpit, mude o seletor de ambiente para Live.
Gere uma chave pgz_live_ (passo 1, agora em Live).
Cadastre a URL de webhook e gere o secret de produção — eles são separados dos de sandbox.
Troque a chave nas suas requisições para a chave pgz_live_.

Live confirma pagamentos reais

Ao configurar o webhook em Live, o cockpit avisa: "Webhooks de produção confirmam pagamentos reais." Confira tudo no sandbox antes.

9. Use um domínio próprio no checkout

Por padrão, o checkout_url fica em sualoja.pgz.link. Você pode usar um endereço seu, como pay.sualoja.com.br.

Em Configurações → Integrações → Domínio, preencha Domínio e clique em Adicionar. A plataforma mostra um registro CNAME — tipo, nome e valor. Crie esse CNAME no painel onde você comprou o domínio.

Depois, clique em Verificar.

O domínio não se verifica sozinho

Não há verificação automática. Depois de criar o CNAME, você clica em Verificar. O status passa por: pendente → verificando → ativo (ou falhou, com o motivo). A propagação do DNS pode levar alguns minutos; se ainda não achou o CNAME, tente de novo mais tarde.

Enquanto o domínio não fica ativo, o checkout continua funcionando em sualoja.pgz.link. Você nunca fica sem checkout.

Comece aqui ​

1. Crie a chave de API ​

2. Test e live: test nunca cobra ​

3. Onde pôr a chave ​

4. Sua primeira chamada: crie uma cobrança ​

5. Cadastre o webhook, gere o secret e verifique a assinatura ​

6. Simule um pagamento no sandbox ​

7. Como saber que funcionou ​

8. Passe para produção ​

9. Use um domínio próprio no checkout ​