# SDK (/zh/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="SDK 仓库" />

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

官方 SDK，无需手写 `fetch` 即可集成 PayZu Pix API。覆盖所有端点、Bearer Auth 以及完整的 schema 类型。目前在包管理平台发布了两个包，都叫 `payzu-pix`，另外还有可直接从仓库安装的 Go 模块：

| 语言      | 包                                                                        | 安装                                        |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| Node.js | npm 上的 [`payzu-pix`](https://www.npmjs.com/package/payzu-pix)            | `npm install payzu-pix`                   |
| Python  | PyPI 上的 [`payzu-pix`](https://pypi.org/project/payzu-pix/)               | `pip install payzu-pix`                   |
| Go      | [`payzu-sdks/go`](https://github.com/PayZuAI/payzu-sdks/tree/main/go) 模块 | `go get github.com/PayZuAI/payzu-sdks/go` |

<Callout type="info">
  仓库中还有一个由同一份 OpenAPI 生成的 **PHP** 客户端，目前尚未发布到
  Packagist：暂时请直接从仓库使用。本页示例覆盖 Node 与 Python。
</Callout>

生产环境 base URL：`https://api.payzu.processamento.com/v1`。使用 onboarding 时签发的 Bearer token 认证。金额始终以巴西雷亚尔（BRL）计。

## 快速上手 [#快速上手]

<Steps>
  <Step>
    ### 安装 [#安装]

    <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>
    ### 初始化 client [#初始化-client]

    通过环境变量 `PAYZU_TOKEN` 传入 Bearer token。切勿将 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">
          `PayZu` facade（payzu-pix 1.0.0+）已默认指向生产环境 base URL `https://api.payzu.processamento.com/v1`。仅当需要指向其他 host 时，才在构造函数里传 `baseUrl`。
        </Callout>

        <Accordions type="single">
          <Accordion title="由 OpenAPI 生成的 client（进阶）">
            同一个包也导出了生成的 client（`Configuration` 和各 `*Api` 类），供需要精细控制 base URL 或 `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">
          安装包名为 `payzu-pix`，但 Python 中的 import 为 `payzu_pix`。`host` 已默认为该值，这里显式传入只是为了更清晰。
        </Callout>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### 创建第一笔 Pix 收款 [#创建第一笔-pix-收款]

    用上一步的 client 调用 [`POST /pix`](/docs/pix-processamento/endpoints/pix-operations/post_pix)。仅 `amount`（以雷亚尔计，最小为 1）为必填。`clientReference` 是你的外部订单引用，同时充当幂等键。

    <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>

    响应是一个 `Transaction`，包含 `id`、`status`、`qrCodeText`（复制粘贴码）、`qrCodeUrl` 和 `qrCodeBase64`。所有端点都遵循这一模式，详见 [API 参考](/docs/pix-processamento/endpoints)。

    <Callout type="info">
      金额始终以\*\*雷亚尔（BRL）\*\*计。`99.90` 即 R$ 99,90。单笔收款最小金额为 R$ 1,00。
    </Callout>

    <Callout type="warn">
      `clientReference` 是幂等键。重试同一笔收款时，请重发**相同**的 `clientReference`；切勿每次尝试都生成新值。这样 API 会返回已创建的收款，而不是重复创建。
    </Callout>
  </Step>
</Steps>

## 完整示例 [#完整示例]

单文件，可直接复制运行。运行前先在环境中设置 `PAYZU_TOKEN`。

<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>

## 工作原理 [#工作原理]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;OpenAPI&#x22;] --> B[&#x22;docs.payzu.com.br/openapi.json&#x22;]
  B --> C[&#x22;每日 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;/zh/docs/pix-processamento/endpoints&#x22; &#x22;Endpoints&#x22;
  click B &#x22;/openapi.json&#x22; &#x22;OpenAPI&#x22;
`"
/>

SDK 会根据本文档的 `openapi.json` 自动重新生成。

## Bug、疑问或建议 [#bug疑问或建议]

| 反馈渠道                                                                                 | 何时                      |
| ------------------------------------------------------------------------------------ | ----------------------- |
| [github.com/PayZuAI/payzu-sdks/issues](https://github.com/PayZuAI/payzu-sdks/issues) | SDK bug（无法编译、缺少方法、类型错误） |
| [suporte.payzu.com.br](https://suporte.payzu.com.br)                                 | API 或账户问题               |
| [docs.payzu.com.br](https://docs.payzu.com.br)                                       | 使用疑问                    |