Empiece aquí

Esta guía lo lleva de su primera clave hasta su primer payment link pagado. Empiece en el sandbox. Nada aquí cobra dinero real hasta que cambie la clave a producción.

El cockpit es https://app.pgz.link. La API es https://api.pgz.link.

1. Cree la clave de API

En el cockpit, abra Configurações → Integrações (Configuración → Integraciones). Arriba a la derecha, deje el selector de entorno en Sandbox.

En Chave de API (Clave de API), complete Nome da chave (nombre de la clave — por ejemplo, "Backend de prueba") y haga clic en Gerar chave (Generar clave).

La clave empieza con pgz_test_ en el sandbox y pgz_live_ en producción.

La clave se muestra una sola vez

La clave en texto plano se muestra solo al momento de crearla. Guárdela en un lugar seguro. Si pierde la clave, no hay forma de recuperarla — genere una nueva y elimine la anterior.

Lo que existe y lo que no:

• Revocar: sí. El botón de papelera revoca la clave. Deja de funcionar de inmediato.
• Rotar: no existe. Para reemplazar una clave, genere una nueva y revoque la anterior.
• Alcances (scopes): usted no los elige. Toda clave creada en el cockpit recibe acceso completo a la API.

2. Test vs live: test nunca cobra

Cada clave pertenece a un entorno, y los dos están aislados.

• Una clave pgz_test_ nunca alcanza al proveedor de pago y nunca crea un cobro real.
• Una clave pgz_live_ opera en producción.

Los recursos creados en un entorno son invisibles en el otro.

Producción usa dinero real

Al crear claves en Live, el cockpit advierte: "Chaves de produção criam cobranças com dinheiro real." (Las claves de producción crean cobros con dinero real.) Empiece siempre en el sandbox.

3. Dónde poner la clave

La clave va en el header Authorization, en formato Bearer:

Authorization: Bearer pgz_test_...

4. Su primera llamada: cree un payment link

Este comando crea un payment link de R$ 2.500,00. Reemplace la clave por la suya.

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:

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

• amount: 250000 son R$ 2.500,00 (valor en centavos).
• reference es su clave de conciliación. Vuelve en cada lectura y en cada webhook. Use el número de su pedido.
• El header Idempotency-Key protege contra cobros duplicados: si la misma solicitud llega dos veces (una falla de red, un retry), la segunda devuelve la respuesta de la primera en vez de crear otro cobro. Use una cadena única por solicitud — recomendamos un UUID.

El checkout_url está en sualoja.pgz.link. Aquí, sualoja es el slug de su tienda — el identificador que usted define en el cockpit. Con un dominio propio (paso 9), esa dirección pasa a ser la suya.

Tome el checkout_url y envíelo a su cliente. Él paga en esa página.

El camino principal es PIX. La tarjeta de crédito también existe, con cuotas — los detalles están en la Referencia.

5. Registre el webhook, genere el secret y verifique la firma

El webhook es cómo usted se entera de que el pago fue confirmado.

En Configurações → Integrações → Webhook, complete URL de webhook con la dirección de su servidor y haga clic en Salvar URL (Guardar URL). Luego haga clic en Gerar secret (Generar secret).

El secret se muestra una sola vez

El secret de firma se muestra solo cuando lo genera. Guárdelo. Para reemplazarlo, use Rotacionar secret (Rotar secret) — el nuevo valor también se muestra una sola vez.

En cada evento, la plataforma envía un POST a su URL con este header:

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

Para verificar: calcule el HMAC-SHA256 del texto "{t}.{body}" (el timestamp, un punto y el cuerpo bruto de la solicitud) usando su secret, y compárelo con el valor v1. Rechace entregas donde t esté a más de 5 minutos del momento actual.

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);
}

Los eventos que usted recibe: payment.succeeded, payment.failed y payment.cancelled.

Responda siempre 2xx

Una entrega solo cuenta como exitosa con una respuesta 2xx. Una falla dispara reintentos con espera creciente. El mismo evento puede llegar más de una vez — procese cada event.id una sola vez.

6. Simule un pago en el sandbox

En el sandbox usted cierra el ciclo sin gastar dinero. Simule el resultado de un link de prueba:

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 mueve el pago al estado pedido y dispara el webhook correspondiente, firmado igual que en producción. Valores de outcome: succeeded, failed, expired.

Este endpoint solo existe en el sandbox. Con una clave pgz_live_, devuelve 403.

7. Cómo saber que funcionó

Dos formas:

1. Su webhook. ¿Recibió payment.succeeded para el reference correcto? Esa es la fuente de la verdad.
2. El panel "Últimas entregas" (Últimas entregas) en el cockpit (en Integraciones). Muestra las últimas entregas de webhook: el evento, cuándo, el estado y el número de intentos. Un botón Atualizar (Actualizar) recarga la lista.

"Últimas entregas" no muestra el cuerpo de la respuesta

El panel muestra evento, hora, estado e intentos. No muestra el cuerpo de la respuesta de su servidor ni el payload enviado. Para depurar el contenido, registre la solicitud de su lado.

No hay endpoint de consulta de eventos

Los eventos se entregan por webhook. No existe un endpoint de la API para listar o buscar eventos pasados. Si su servidor puede caerse, guarde los webhooks que recibe.

8. Pase a producción

Cuando el flujo funcione en el sandbox:

1. En el cockpit, cambie el selector de entorno a Live.
2. Genere una clave pgz_live_ (paso 1, ahora en Live).
3. Registre la URL de webhook y genere el secret de producción — son separados de los del sandbox.
4. Reemplace la clave en sus solicitudes por la clave pgz_live_.

Live confirma pagos reales

Al configurar el webhook en Live, el cockpit advierte: "Webhooks de produção confirmam pagamentos reais." (Los webhooks de producción confirman pagos reales.) Revise todo en el sandbox primero.

9. Use un dominio propio para el checkout

Por defecto, el checkout_url está en sualoja.pgz.link. Usted puede usar una dirección suya, como pay.sualoja.com.br.

En Configurações → Integrações → Domínio (Dominio), complete Domínio y haga clic en Adicionar (Agregar). La plataforma muestra un registro CNAME — tipo, nombre y valor. Cree ese CNAME en el panel donde compró el dominio.

Luego haga clic en Verificar.

El dominio no se verifica solo

No hay verificación automática. Después de crear el CNAME, usted hace clic en Verificar. El estado pasa por: pending → verifying → active (o failed, con el motivo). La propagación del DNS puede tardar algunos minutos; si aún no encontró el CNAME, intente de nuevo más tarde.

Mientras el dominio no está activo, el checkout sigue funcionando en sualoja.pgz.link. Usted nunca se queda sin checkout.