# Postman (/docs/pix-processamento/postman)

<QuickLinks>
  <QuickLink href="https://dev.payzu.com.br" title="Postman docs" />

  <QuickLink href="/openapi.json" title="OpenAPI" />

  <QuickLink href="/api-scalar" title="Scalar" />

  <QuickLink href="/api-swagger" title="Swagger" />
</QuickLinks>

A collection oficial PayZu Pix está publicada em &#x2A;*[dev.payzu.com.br](https://dev.payzu.com.br)** (Postman) com **Bearer Auth** via `{{token}}` e **3 ambientes** prontos: Sandbox, Production e Mock.

O JSON servido em [docs.payzu.com.br/payzu-pix.postman\_collection.json](https://docs.payzu.com.br/payzu-pix.postman_collection.json) cobre as 48 rotas `/v1`. As pastas seguem o caminho da rota, um segmento por pasta: `POST /user/callbacks/resend/webhook` fica em `user › callbacks › resend › webhook`. Cada request traz um exemplo de resposta salvo por status.

## Importar a collection [#importar-a-collection]

<PostmanButton />

Ou via URL no Postman: **Import → Link**:

```
https://docs.payzu.com.br/payzu-pix.postman_collection.json
```

## Setup em 3 passos [#setup-em-3-passos]

<Steps>
  <Step>
    ### Importar no seu workspace [#importar-no-seu-workspace]

    Clica em **Run in Postman** acima. A collection é forkada pro seu workspace pessoal, com toda a estrutura: folders, autenticação, exemplos.
  </Step>

  <Step>
    ### Configurar o token [#configurar-o-token]

    Na collection PayZu Pix → aba **Variables**:

    | Variável  | Valor                                             |
    | --------- | ------------------------------------------------- |
    | `baseUrl` | `https://api.payzu.processamento.com/v1` (padrão) |
    | `token`   | Seu Bearer token PayZu                            |

    `baseUrl` e `token` são as únicas variáveis da collection: a autenticação fica no nível dela e cada requisição herda o header `Authorization: Bearer {{token}}`, sem token próprio. Isso descreve o JSON servido em [docs.payzu.com.br](https://docs.payzu.com.br/payzu-pix.postman_collection.json); se no seu fork alguma requisição tiver token próprio, ele veio de uma cópia antiga, e reimportar pelo link resolve.
  </Step>

  <Step>
    ### Testar uma chamada [#testar-uma-chamada]

    Antes de mandar qualquer coisa, troque o `baseUrl` para o sandbox (`https://pix.sandbox.payzu.dev/v1`) ou selecione o environment **Sandbox**.

    <Callout type="warn">
      Com o `baseUrl` padrão você está em **produção**. A cobrança criada é real, e pagar o QR Code move dinheiro de verdade.
    </Callout>

    Aí sim: &#x2A;*pix → Create Charge (Pix deposit)** → **Send**. O exemplo já vem preenchido com `amount` e `clientReference`, e volta o `qrCodeText`.
  </Step>
</Steps>

## Sandbox: o jeito recomendado de testar sem produção [#sandbox-o-jeito-recomendado-de-testar-sem-produção]

Troque o `baseUrl` para o sandbox e rode a collection inteira contra uma API de verdade, com credencial de 24 horas e sem cadastro:

```
https://pix.sandbox.payzu.dev/v1
```

São as mesmas rotas `/v1`, então o que funciona aqui funciona em produção trocando só o host. Diferente do mock, o sandbox **guarda estado**: a cobrança que você cria pode ser paga, o saque muda de status e o webhook chega de verdade no seu endpoint.

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/sandbox/credencial" title="Gerar credencial de sandbox" />

  <QuickLink href="/docs/pix-processamento/sandbox/cenarios" title="Cenários de teste" />

  <QuickLink href="/docs/pix-processamento/sandbox/webhooks" title="Webhooks no sandbox" />
</QuickLinks>

## Mock Server [#mock-server]

O mock existe para o caso em que você ainda não quer nem credencial de sandbox, ou precisa **contornar CORS** em ferramenta web. Ele devolve exemplo fixo e não guarda estado.

```
https://a8aa4f94-6b53-4994-bc60-7b2347f008e1.mock.pstmn.io/v1
```

<Callout type="warn">
  Mantenha o `/v1` no fim da URL. Sem ele o mock responde 404 em tudo.
</Callout>

| Request                           | Resposta mock                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| `POST /v1/pix`                    | `{ id, status: "PENDING", amount, type: "DEPOSIT", qrCodeText, qrCodeBase64, qrCodeUrl }` |
| `GET /v1/pix?clientReference=...` | o mesmo objeto, sempre `PENDING`                                                          |
| `GET /v1/user/balance`            | `{ balanceAvailable: 231.46, balanceBlocked: 0 }`                                         |

<Callout type="info">
  O mock devolve sempre o mesmo exemplo, independente do que você mandar: o `amount` da resposta não acompanha o da requisição e o status nunca avança. Para ver transação mudar de estado, use o sandbox.
</Callout>

## Boas práticas [#boas-práticas]

* **Crie um fork** da collection oficial em vez de editar a original. Forks recebem updates upstream.
* **Use environments** pra trocar `baseUrl` entre sandbox e produção (`https://pix.sandbox.payzu.dev/v1` vs `https://api.payzu.processamento.com/v1`).
* **Snippets de código**: clica em `</>` no canto direito de qualquer request pra exportar em curl, Node, Python, Go, PHP, etc.
* **Monitor**: ative Postman Monitor pra testar a API a cada 5 min e receber alerta se cair.

## Comparação com outros visualizadores [#comparação-com-outros-visualizadores]

| Recurso             | Postman               | [Scalar](/api-scalar) | [Swagger](/api-swagger) |
| ------------------- | --------------------- | --------------------- | ----------------------- |
| Try-it com CORS     | **Sim (sem browser)** | Não (CORS bloqueia)   | Não (CORS bloqueia)     |
| Mock server público | **Sim**               | Não                   | Não                     |
| Environments        | **Sim**               | Não                   | Não                     |
| Monitor agendado    | **Sim**               | Não                   | Não                     |
| Code snippets       | Sim                   | Sim                   | Sim                     |
| Try-it no browser   | Não (Postman Web sim) | Sim                   | Sim                     |
| Sem instalação      | Postman Web           | **Sim**               | **Sim**                 |