Sandbox y simulación de pago

Una clave pgz_test_ opera en un entorno aislado que nunca toca al proveedor ni mueve dinero. Usted corre el ciclo completo:

1. POST /v1/payment_links con una clave pgz_test_ → link de prueba + checkout_url de prueba.
2. Abrir el checkout_url.
3. Simular el resultado con POST /v1/payment_links/{id}/simulate_payment (disponible solo en el sandbox):

campo	tipo	requerido	constraint
outcome	string	sí	succeeded | failed | expired
payment_method	string	no	pix | card; default pix

La simulación mueve el pago al estado pedido y dispara el webhook correspondiente (payment.succeeded / payment.failed) firmado con el secret de su endpoint de prueba, exactamente como en producción. Llamar este endpoint con una clave pgz_live_ → 403 (not_available_in_live).

---

Metadata

• metadata es un objeto clave-valor libre, con como máximo 20 claves.
• El namespace pgz_* está reservado por la plataforma: una clave con ese prefijo enviada por el integrador → 400 (reserved_metadata_key, param = la clave).
• metadata se persiste y se devuelve en cada objeto PaymentLink y Payment.

reference (≤ 255 chars) es distinto de metadata: es la clave primaria de conciliación del integrador, presente en cada Payment y webhook.

---