Quickstart PIX

De cero a un pago de prueba confirmado. Use una clave de sandbox — nada aquí cobra dinero real.

1. Consiga una clave de prueba

En el cockpit (https://app.pgz.link), en Configurações → Integrações, con el entorno en Sandbox, haga clic en Gerar chave (Generar clave). Empieza con pgz_test_.

La clave se muestra una sola vez. Guárdela.

2. Cree el payment link

amount es en 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" }'

Usted recibe un checkout_url:

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

En el checkout_url, sualoja es el slug de su tienda (usted lo define en el cockpit).

3. Envíe el checkout_url

Envíelo al cliente. Él paga en la página alojada.

4. Reciba el webhook

Registre la URL y genere el secret. Al pagar, llega un POST con payment.succeeded. Verifique la firma (el header Pagooz-Signature) y revise el reference. El paso a paso está en Empiece aquí.

5. Pruebe sin esperar un pago real

En el sandbox, fuerce el 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" }'

Esto dispara el webhook payment.succeeded, firmado igual que en producción. Si su servidor lo recibió y verificó, el ciclo está cerrado.

Errores comunes

Los errores siempre vienen en el mismo formato: { "error": { "code", "message", "param", "request_id" } }. Cite el request_id en cualquier solicitud de soporte.

• 401 invalid_api_key — la clave está mal, falta o fue revocada. Revise el header Authorization: Bearer pgz_test_... y si la clave es del entorno correcto.
• 400 invalid_request o unknown_parameter — el cuerpo tiene un campo inválido, faltante, o una clave que no existe. El campo problemático viene en param.
• 409 idempotency_key_reuse — reusó una Idempotency-Key con un cuerpo diferente. Use una clave nueva para un cobro nuevo.

Próximo paso

¿Listo para el resto — producción, dominio propio, tarjeta? Vea Empiece aquí. La referencia completa de los endpoints está en Payment Links.