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).

Transferência bancária no sandbox. outcome: "succeeded" sobre um pagamento por transferência executa a mesma conferência de produção: fecha a conferência, grava a previsão de liquidação e dispara o payment.succeeded. Como em produção, só vale depois que o comprovante foi enviado no checkout — simular antes disso retorna 400 (ted_not_pending_review), com a mensagem dizendo o que falta. É de propósito: um sandbox que aceita o que produção recusa ensina o integrador errado.

---

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.

---