PIX Quickstart

From zero to a confirmed test payment. Use a sandbox key — nothing here charges real money.

1. Get a test key

In the cockpit (https://app.pgz.link), under Configurações → Integrações, with the environment on Sandbox, click Gerar chave (Generate key). It starts with pgz_test_.

The key is shown only once. Store it.

2. Create the payment link

amount is in cents: R$ 2.500,00 → 250000.

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" }'

You get a checkout_url:

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

In the checkout_url, sualoja is your store slug (you set it in the cockpit).

3. Send the checkout_url

Send it to the customer. They pay on the hosted page.

4. Receive the webhook

Register the URL and generate the secret. On payment, a POST arrives with payment.succeeded. Verify the signature (the Pagooz-Signature header) and check the reference. The step by step is in Get started.

5. Test without waiting for a real payment

In the sandbox, force the outcome:

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" }'

This fires the payment.succeeded webhook, signed just like production. If your server received and verified it, the loop is closed.

Common errors

Errors always come in the same shape: { "error": { "code", "message", "param", "request_id" } }. Cite the request_id in any support request.

• 401 invalid_api_key — the key is wrong, missing, or revoked. Check the Authorization: Bearer pgz_test_... header and whether the key is for the right environment.
• 400 invalid_request or unknown_parameter — the body has an invalid or missing field, or a key that does not exist. The offending field comes in param.
• 409 idempotency_key_reuse — you reused an Idempotency-Key with a different body. Use a new key for a new charge.

Next step

Ready for the rest — production, custom domain, card? See Get started. The full endpoint reference is in Payment Links.