Sandbox e simulação de pagamento

Uma chave pgz_test_ opera num ambiente isolado que nunca toca o provedor nem gera dinheiro. Você roda o ciclo completo:

1. POST /v1/payment_links com uma chave pgz_test_ → link de teste + checkout_url de teste.
2. Abrir o checkout_url.
3. Simular o resultado com POST /v1/payment_links/{id}/simulate_payment (disponível somente no sandbox):

campo	tipo	obrig.	constraint
outcome	string	sim	succeeded | failed | expired
payment_method	string	não	pix | card; default pix

A simulação move o pagamento ao estado pedido e dispara o webhook correspondente (payment.succeeded / payment.failed) assinado com o secret do seu endpoint de teste, exatamente como em produção. Chamar este endpoint com uma chave pgz_live_ → 403 (not_available_in_live).

---

Metadata

• metadata é um objeto chave-valor livre, com no máximo 20 chaves.
• O namespace pgz_* é reservado da plataforma: uma chave com esse prefixo enviada pelo integrador → 400 (reserved_metadata_key, param = a chave).
• metadata é persistido e devolvido em todo objeto PaymentLink e Payment.

reference (≤ 255 chars) é distinto de metadata: é a chave primária de conciliação do integrador, presente em todo Payment e webhook.

---