# SDKs (/docs/pix-processamento/sdks)



<QuickLinks>
  <QuickLink href="https://www.npmjs.com/package/payzu-pix" title="npm payzu-pix" />

  <QuickLink href="https://pypi.org/project/payzu-pix/" title="PyPI payzu-pix" />

  <QuickLink href="https://github.com/PayZuPlus/payzu-sdks" title="Repo dos SDKs" />

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

SDKs oficiais para integrar com a API PayZu Pix sem montar `fetch` na mão. Cobrem todos os endpoints, Bearer Auth e a tipagem completa dos schemas. Hoje há dois pacotes publicados, ambos chamados `payzu-pix`:

| Linguagem | Pacote                                                        | Instalação              |
| --------- | ------------------------------------------------------------- | ----------------------- |
| Node.js   | [`payzu-pix`](https://www.npmjs.com/package/payzu-pix) no npm | `npm install payzu-pix` |
| Python    | [`payzu-pix`](https://pypi.org/project/payzu-pix/) no PyPI    | `pip install payzu-pix` |

Base URL de produção: `https://api.payzu.processamento.com/v1`. Autenticação por Bearer token emitido no onboarding. Valores sempre em reais (BRL).

## Quickstart [#quickstart]

<Steps>
  <Step>
    ### Instalar [#instalar]

    <Tabs items="['Node.js', 'Python']">
      <Tab value="Node.js">
        ```bash
        npm install payzu-pix
        ```
      </Tab>

      <Tab value="Python">
        ```bash
        pip install payzu-pix
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Inicializar o client [#inicializar-o-client]

    Passe o Bearer token pela variável de ambiente `PAYZU_TOKEN`. Nunca escreva o token direto no código.

    <Tabs items="['Node.js', 'Python']">
      <Tab value="Node.js">
        ```ts
        import { PayZu } from 'payzu-pix';

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

        <Callout type="info">
          A facade `PayZu` (payzu-pix 1.0.0+) já aponta para a base URL de produção `https://api.payzu.processamento.com/v1`. Passe `baseUrl` no construtor apenas se precisar apontar para outro host.
        </Callout>

        <Accordions type="single">
          <Accordion title="Client gerado do OpenAPI (avançado)">
            O mesmo pacote também exporta o client gerado (`Configuration` e as classes `*Api`) para quem precisa de controle fino da base URL ou do `fetch`:

            ```ts
            import { Configuration, PixOperationsApi } from 'payzu-pix';

            const config = new Configuration({
              accessToken: process.env.PAYZU_TOKEN,
              basePath: 'https://api.payzu.processamento.com/v1',
            });

            const pix = new PixOperationsApi(config);
            ```
          </Accordion>
        </Accordions>
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import payzu_pix

        config = payzu_pix.Configuration(
            host='https://api.payzu.processamento.com/v1',
            access_token=os.environ['PAYZU_TOKEN'],
        )
        client = payzu_pix.ApiClient(config)
        api = payzu_pix.PixOperationsApi(client)
        ```

        <Callout type="info">
          O pacote instala como `payzu-pix`, mas o import em Python é `payzu_pix`. O `host` já vem com esse valor por padrão; passamos explícito só para deixar claro.
        </Callout>
      </Tab>
    </Tabs>
  </Step>

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

    Chame [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix) com o client do passo anterior. Só `amount` (em reais, mínimo 1) é obrigatório. `clientReference` é a sua referência externa do pedido e serve de chave de idempotência.

    <Tabs items="['Node.js', 'Python']">
      <Tab value="Node.js">
        ```ts
        const charge = await payzu.pix.create({
          amount: 99.90,
          clientReference: 'order-1234',
          callbackUrl: 'https://seusite.com.br/webhooks/payzu',
        });

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

      <Tab value="Python">
        ```python
        request = payzu_pix.PostPixRequest(
            amount=99.90,
            client_reference='order-1234',
            callback_url='https://seusite.com.br/webhooks/payzu',
        )
        charge = api.post_pix(request)

        print(charge.id, charge.status, charge.qr_code_text)
        ```
      </Tab>
    </Tabs>

    A resposta é uma `Transaction` com `id`, `status`, `qrCodeText` (copia-e-cola), `qrCodeUrl` e `qrCodeBase64`. Todos os endpoints seguem esse padrão, veja a [Referência da API](/docs/pix-processamento/endpoints).

    <Callout type="info">
      Valores sempre em &#x2A;*reais (BRL)**. `99.90` é R$ 99,90. O valor mínimo de uma cobrança é R$ 1,00.
    </Callout>

    <Callout type="warn">
      `clientReference` é a chave de idempotência. Num retry da mesma cobrança, reenvie o **mesmo** `clientReference`; nunca gere um novo a cada tentativa. Assim a API devolve a cobrança já criada em vez de duplicar.
    </Callout>
  </Step>
</Steps>

## Exemplo completo [#exemplo-completo]

Arquivo único, pronto para copiar e rodar. Configure `PAYZU_TOKEN` no ambiente antes de executar.

<Tabs items="['Node.js', 'Python']">
  <Tab value="Node.js">
    ```ts
    import { PayZu, PayZuError } from 'payzu-pix';

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

    async function main() {
      const charge = await payzu.pix.create({
        amount: 99.90,
        clientReference: 'order-1234',
        callbackUrl: 'https://seusite.com.br/webhooks/payzu',
      });

      console.log(charge.id, charge.status, charge.qrCodeText);
    }

    main().catch((error) => {
      if (error instanceof PayZuError) {
        console.error(error.status, error.code, error.message);
        return;
      }
      throw error;
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import payzu_pix

    config = payzu_pix.Configuration(
        host='https://api.payzu.processamento.com/v1',
        access_token=os.environ['PAYZU_TOKEN'],
    )

    with payzu_pix.ApiClient(config) as client:
        api = payzu_pix.PixOperationsApi(client)
        request = payzu_pix.PostPixRequest(
            amount=99.90,
            client_reference='order-1234',
            callback_url='https://seusite.com.br/webhooks/payzu',
        )
        try:
            charge = api.post_pix(request)
            print(charge.id, charge.status, charge.qr_code_text)
        except payzu_pix.ApiException as error:
            print(error.status, error.body)
    ```
  </Tab>
</Tabs>

## Como funcionam [#como-funcionam]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;OpenAPI&#x22;] --> B[&#x22;docs.payzu.com.br/openapi.json&#x22;]
  B --> C[&#x22;GitHub Action diaria&#x22;]
  C --> D[&#x22;openapi-generator-cli&#x22;]
  D --> N[&#x22;SDK Node&#x22;]
  D --> P[&#x22;SDK Python&#x22;]
  N --> NR[&#x22;npm&#x22;]
  P --> PR[&#x22;PyPI&#x22;]

  click A &#x22;/docs/pix-processamento/endpoints&#x22; &#x22;Endpoints&#x22;
  click B &#x22;/openapi.json&#x22; &#x22;OpenAPI&#x22;
  click C &#x22;https://github.com/PayZuPlus/payzu-sdks/actions&#x22; &#x22;Workflow&#x22;
`"
/>

O workflow `Generate SDKs` ([generate.yml](https://github.com/PayZuPlus/payzu-sdks/blob/main/.github/workflows/generate.yml)) sincroniza diariamente do `openapi.json` da doc e regenera o client via `openapi-generator-cli`. O SDK Node combina esse núcleo gerado com a facade `PayZu` escrita à mão, que é o contrato estável do pacote. O SDK Python é 100% gerado. Assim os dois acompanham a API sem trabalho manual.

## Bug, dúvida ou sugestão [#bug-dúvida-ou-sugestão]

| Onde reportar                                                                            | Quando                                              |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [github.com/PayZuPlus/payzu-sdks/issues](https://github.com/PayZuPlus/payzu-sdks/issues) | Bug no SDK (não compila, falta método, tipo errado) |
| [suporte.payzu.com.br](https://suporte.payzu.com.br)                                     | Bug na API ou conta                                 |
| [docs.payzu.com.br](https://docs.payzu.com.br)                                           | Dúvida de uso                                       |