Quickstart PIX

O caminho mais curto: do zero a um pagamento de teste confirmado. Use uma chave de sandbox — nada aqui cobra dinheiro real.

1. Pegue uma chave de teste

No cockpit (https://app.pgz.link), em Configurações → Integrações, com o ambiente em Sandbox, clique em Gerar chave. A chave começa com pgz_test_.

A chave aparece uma vez só. Guarde-a.

2. Crie a cobrança

amount é em centavos: R$ 2.500,00 → 250000.

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 um checkout_url:

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

No checkout_url, sualoja é o slug da sua loja (você define no cockpit).

3. Envie o checkout_url

Mande o checkout_url ao seu cliente. Ele paga nessa página hospedada.

4. Receba o webhook

Cadastre a URL de webhook e gere o secret em Integrações. Quando o pagamento é confirmado, a plataforma faz um POST na sua URL com o evento payment.succeeded.

Verifique a assinatura (header Pagooz-Signature) e confira o reference. O passo a passo está em Comece aqui.

5. Teste sem esperar um pagamento real

No sandbox, force o resultado:

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 dispara o webhook payment.succeeded, assinado igual à produção. Se o seu servidor recebeu e verificou, o ciclo está fechado.

Erros comuns

Os erros vêm sempre no mesmo formato: { "error": { "code", "message", "param", "request_id" } }. Cite o request_id em qualquer suporte.

• 401 invalid_api_key — a chave está errada, ausente ou revogada. Confira o header Authorization: Bearer pgz_test_... e se a chave é do ambiente certo.
• 400 invalid_request ou unknown_parameter — o corpo tem um campo inválido, faltando, ou uma chave que não existe. O campo problemático vem em param.
• 409 idempotency_key_reuse — você reusou um Idempotency-Key com um corpo diferente. Use uma chave nova para uma cobrança nova.

Próximo passo

Pronto para o resto — produção, domínio próprio, cartão? Veja Comece aqui. A referência completa dos endpoints está em Payment Links.