Sandbox and payment simulation

A pgz_test_ key operates in an isolated environment that never touches the provider or moves money. You run the full cycle:

1. POST /v1/payment_links with a pgz_test_ key → test link + test checkout_url.
2. Open the checkout_url.
3. Simulate the outcome with POST /v1/payment_links/{id}/simulate_payment (available only in the sandbox):

field	type	required	constraint
outcome	string	yes	succeeded | failed | expired
payment_method	string	no	pix | card; default pix

The simulation moves the payment to the requested state and fires the matching webhook (payment.succeeded / payment.failed) signed with your test endpoint's secret, exactly like in production. Calling this endpoint with a pgz_live_ key → 403 (not_available_in_live).

---

Metadata

• metadata is a free key-value object, with at most 20 keys.
• The pgz_* namespace is reserved by the platform: a key with that prefix sent by the integrator → 400 (reserved_metadata_key, param = the key).
• metadata is persisted and returned on every PaymentLink and Payment object.

reference (≤ 255 chars) is distinct from metadata: it is the integrator's primary reconciliation key, present on every Payment and webhook.

---