# Primeiros passos (/docs/pix-processamento/getting-started)



<PixSeal />

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints" title="Referência API" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossário" />

  <QuickLink href="/docs/pix-processamento/concepts" title="Conceitos" />

  <QuickLink href="/docs/pix-processamento/authentication" title="Autenticação" />

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

  <QuickLink href="/docs/pix-processamento/med" title="MED" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Criar conta&#x22;] --> B[&#x22;Testar token&#x22;]
  B --> C[&#x22;Criar cobrança&#x22;]
  C --> D[&#x22;Receber callback&#x22;]

  click A &#x22;https://abrirconta.payzu.com.br&#x22; &#x22;Abrir conta PayZu&#x22;
  click B &#x22;/docs/pix-processamento/endpoints/account/get_user_balance&#x22; &#x22;GET /user/balance&#x22;
  click C &#x22;/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;POST /pix&#x22;
  click D &#x22;/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

<Steps>
  <Step>
    ### Criar conta [#criar-conta]

    Abra sua conta em [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br). Após aprovação você recebe:

    * **Bearer token**, usado em todas as requisições. Ver [Autenticação](/docs/pix-processamento/authentication).
    * **Base URL**, `https://api.payzu.processamento.com/v1`.

    <Callout type="warn">
      Guarde o token em vault (Google Secret Manager, AWS Secrets, etc).
      Nunca commite em repositório nem exponha no front-end.
    </Callout>
  </Step>

  <Step>
    ### Testar autenticação [#testar-autenticação]

    Para confirmar que o token funciona, consulte o saldo da conta usando o endpoint [`GET /user/balance`](/docs/pix-processamento/endpoints/account/get_user_balance).

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl https://api.payzu.processamento.com/v1/user/balance \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json"
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://api.payzu.processamento.com/v1/user/balance', {
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
        });
        const balance = await res.json();
        ```
      </Tab>
    </Tabs>

    Se voltar o JSON com o saldo, está autenticado. Se retornar `401`, revise o token (espaço, encoding) ou contate o suporte. Ver [códigos HTTP no glossário](/docs/pix-processamento/glossary#códigos-http).
  </Step>

  <Step>
    ### Criar a primeira cobrança Pix [#criar-a-primeira-cobrança-pix]

    Crie uma cobrança via [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix). Schema completo na referência.

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.payzu.processamento.com/v1/pix \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 10.90,
            "generatedName": "João da Silva",
            "generatedDocument": "12345678909",
            "callbackUrl": "https://seusite.com.br/webhooks/payzu",
            "clientReference": "pedido-2025-001"
          }'
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://api.payzu.processamento.com/v1/pix', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 10.90,
            generatedName: 'João da Silva',
            generatedDocument: '12345678909',
            callbackUrl: 'https://seusite.com.br/webhooks/payzu',
            clientReference: 'pedido-2025-001',
          }),
        });
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    A resposta traz `qrCodeText` (copia-e-cola), `qrCodeUrl` e o `id` da transação. Cada campo está explicado no [glossário](/docs/pix-processamento/glossary#campos-comuns-da-api).

    <Callout type="info">
      Valores estão sempre em &#x2A;*reais (BRL)**. `10.90` é R$ 10,90.
    </Callout>
  </Step>

  <Step>
    ### Receber o callback [#receber-o-callback]

    Quando o pagador concluir o Pix, a PayZu envia um `POST` para a `callbackUrl` informada com o objeto da transação atualizado (`status: "COMPLETED"`). Responda com `2xx` em até 5 segundos.

    ```http
    POST /webhooks/payzu
    Content-Type: application/json

    {
      "id": "PAYZU20251123104518DF75D20A8F",
      "status": "COMPLETED",
      "amount": 10.90,
      "clientReference": "pedido-2025-001",
      "endToEndId": "E18236120202511231046s1235ee7",
      "paidAt": "2025-11-23T10:46:26.986Z"
    }
    ```

    Detalhes de retry, payload completo e segurança em [Webhooks](/docs/pix-processamento/webhooks). Se quiser inspecionar ou reenviar manualmente, use [`GET /user/callbacks`](/docs/pix-processamento/endpoints/callbacks/get_user_callbacks).
  </Step>
</Steps>

## Próximos passos [#próximos-passos]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/tutoriais/receive-pix" title="Tutorial · Receber Pix" />

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

  <QuickLink href="/docs/pix-processamento/best-practices" title="Boas práticas" />

  <QuickLink href="/docs/pix-processamento/endpoints" title="Referência da API" />
</QuickLinks>