# Getting started (/en/docs/pix-processamento/getting-started)

<PixSeal />

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints" title="API Reference" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossary" />

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

  <QuickLink href="/docs/pix-processamento/authentication" title="Authentication" />

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

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

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Create account&#x22;] --> B[&#x22;Test token&#x22;]
  B --> C[&#x22;Create charge&#x22;]
  C --> D[&#x22;Receive callback&#x22;]

  click A &#x22;https://abrirconta.payzu.com.br&#x22; &#x22;Open PayZu account&#x22;
  click B &#x22;/en/docs/pix-processamento/endpoints/account/get_user_balance&#x22; &#x22;GET /user/balance&#x22;
  click C &#x22;/en/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;POST /pix&#x22;
  click D &#x22;/en/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>
    ### Create account [#create-account]

    Open your account at [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br). After approval you receive:

    * **Bearer token**, used in all requests. See [Authentication](/docs/pix-processamento/authentication).
    * **Base URL**, `https://api.payzu.processamento.com/v1`.

    <Callout type="warn">
      Store the token in a vault (Google Secret Manager, AWS Secrets, etc).
      Never commit it to a repository or expose it in the front-end.
    </Callout>
  </Step>

  <Step>
    ### Test authentication [#test-authentication]

    To confirm the token works, check the account balance using the [`GET /user/balance`](/docs/pix-processamento/endpoints/account/get_user_balance) endpoint.

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl https://api.payzu.processamento.com/v1/user/balance \
          -H "Authorization: Bearer YOUR_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>

    If the JSON with the balance comes back, you are authenticated. If it returns `401`, check the token (whitespace, encoding) or contact support. See [HTTP codes in the glossary](/docs/pix-processamento/glossary#códigos-http).
  </Step>

  <Step>
    ### Create the first Pix charge [#create-the-first-pix-charge]

    Create a charge via [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix). Full schema in the reference.

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.payzu.processamento.com/v1/pix \
          -H "Authorization: Bearer YOUR_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">
        With the official [`payzu-pix`](/docs/pix-processamento/sdks) SDK:

        The example uses ESM and top-level `await`. Save it as `.mjs` (or set `"type": "module"` in `package.json`).

        ```bash
        npm install payzu-pix
        ```

        ```js
        import { PayZu } from 'payzu-pix';

        const payzu = new PayZu({ token: process.env.PAYZU_TOKEN });

        const charge = await payzu.pix.create({
          amount: 10.90,
          generatedName: 'João da Silva',
          generatedDocument: '12345678909',
          callbackUrl: 'https://seusite.com.br/webhooks/payzu',
          clientReference: 'pedido-2025-001',
        });

        console.log(charge.id, charge.status, charge.qrCodeText);
        ```
      </Tab>
    </Tabs>

    The response brings `qrCodeText` (copy-and-paste), `qrCodeUrl` and the transaction `id`. Each field is explained in the [glossary](/docs/pix-processamento/glossary#common-api-fields).

    <Callout type="info">
      Amounts are always in &#x2A;*reais (BRL)**. `10.90` is R$ 10.90.
    </Callout>
  </Step>

  <Step>
    ### Receive the callback [#receive-the-callback]

    When the payer completes the Pix, PayZu sends a `POST` to the provided `callbackUrl` with the updated transaction object (`status: "COMPLETED"`). Respond with `2xx` within 5 seconds.

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

    {
      "id": "PAYZU20260811K7M2X9QP4T000000",
      "status": "COMPLETED",
      "amount": 10.90,
      "clientReference": "pedido-2025-001",
      "endToEndId": "E18236120202608111046s1235ee7a91",
      "paidAt": "2026-08-11T10:46:26.986Z"
    }
    ```

    Retry details, full payload and security in [Webhooks](/docs/pix-processamento/webhooks). To inspect or manually resend, use [`GET /user/callbacks`](/docs/pix-processamento/endpoints/callbacks/get_user_callbacks).
  </Step>
</Steps>

## Next steps [#next-steps]

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

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

  <QuickLink href="/docs/pix-processamento/best-practices" title="Best practices" />

  <QuickLink href="/docs/pix-processamento/endpoints" title="API Reference" />
</QuickLinks>