# SDKs (/en/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/PayZuAI/payzu-sdks" title="SDKs repo" />

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

Official SDKs to integrate with the PayZu Pix API without hand-rolling `fetch`. They cover every endpoint, Bearer Auth and full schema typing. Two packages are published on registries today, both named `payzu-pix`, plus the Go module you install straight from the repository:

| Language | Package                                                                      | Install                                   |
| -------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| Node.js  | [`payzu-pix`](https://www.npmjs.com/package/payzu-pix) on npm                | `npm install payzu-pix`                   |
| Python   | [`payzu-pix`](https://pypi.org/project/payzu-pix/) on PyPI                   | `pip install payzu-pix`                   |
| Go       | [`payzu-sdks/go`](https://github.com/PayZuAI/payzu-sdks/tree/main/go) module | `go get github.com/PayZuAI/payzu-sdks/go` |

<Callout type="info">
  The repo also ships a **PHP** client generated from the same OpenAPI spec, not
  published on Packagist yet: for now, use it straight from the repository. The
  examples on this page cover Node and Python.
</Callout>

Production base URL: `https://api.payzu.processamento.com/v1`. Authentication uses a Bearer token issued during onboarding. Amounts are always in Brazilian reais (BRL).

## Quickstart [#quickstart]

<Steps>
  <Step>
    ### Install [#install]

    <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>
    ### Initialize the client [#initialize-the-client]

    Pass the Bearer token through the `PAYZU_TOKEN` environment variable. Never hard-code the token.

    <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">
          The `PayZu` facade (payzu-pix 1.0.0+) already points at the production base URL `https://api.payzu.processamento.com/v1`. Pass `baseUrl` in the constructor only if you need a different host.
        </Callout>

        <Accordions type="single">
          <Accordion title="OpenAPI-generated client (advanced)">
            The same package also exports the generated client (`Configuration` and the `*Api` classes) for anyone who needs fine-grained control over the base URL or `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">
          The package installs as `payzu-pix`, but the Python import is `payzu_pix`. `host` already defaults to this value; we pass it explicitly just to be clear.
        </Callout>
      </Tab>
    </Tabs>
  </Step>

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

    Call [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix) with the client from the previous step. Only `amount` (in reais, minimum 1) is required. `clientReference` is your external order reference and acts as the idempotency key.

    <Tabs items="['Node.js', 'Python']">
      <Tab value="Node.js">
        ```ts
        const charge = await payzu.pix.create({
          amount: 99.90,
          clientReference: 'order-1234',
          callbackUrl: 'https://yoursite.com/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://yoursite.com/webhooks/payzu',
        )
        charge = api.post_pix(request)

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

    The response is a `Transaction` with `id`, `status`, `qrCodeText` (copy-and-paste), `qrCodeUrl` and `qrCodeBase64`. Every endpoint follows this pattern, see the [API reference](/docs/pix-processamento/endpoints).

    <Callout type="info">
      Amounts are always in &#x2A;*reais (BRL)**. `99.90` is R$ 99.90. The minimum charge is R$ 1.00.
    </Callout>

    <Callout type="warn">
      `clientReference` is the idempotency key. When retrying the same charge, resend the **same** `clientReference`; never generate a new one per attempt. That way the API returns the existing charge instead of duplicating it.
    </Callout>
  </Step>
</Steps>

## Full example [#full-example]

A single file, ready to copy and run. Set `PAYZU_TOKEN` in your environment before running.

<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://yoursite.com/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://yoursite.com/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>

## How they work [#how-they-work]

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

  click A &#x22;/en/docs/pix-processamento/endpoints&#x22; &#x22;Endpoints&#x22;
  click B &#x22;/openapi.json&#x22; &#x22;OpenAPI&#x22;
`"
/>

The SDKs are regenerated automatically from the `openapi.json` of this documentation.

## Bug, question or suggestion [#bug-question-or-suggestion]

| Where to report                                                                      | When                                                   |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| [github.com/PayZuAI/payzu-sdks/issues](https://github.com/PayZuAI/payzu-sdks/issues) | SDK bug (does not compile, missing method, wrong type) |
| [suporte.payzu.com.br](https://suporte.payzu.com.br)                                 | API or account bug                                     |
| [docs.payzu.com.br](https://docs.payzu.com.br)                                       | Usage question                                         |