PayZu Docs

Node、Python 和 Go 的官方库，让你不用手写请求就能对接：用 npm、pip 或 go get 安装，传入 token，几分钟就创建第一笔收款，类型一应俱全。

npm payzu-pix PyPI payzu-pix SDK 仓库 API 参考

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

语言	包	安装
Node.js	npm 上的 `payzu-pix`	`npm install payzu-pix`
Python	PyPI 上的 `payzu-pix`	`pip install payzu-pix`
Go	`payzu-sdks/go` 模块	`go get github.com/PayZuAI/payzu-sdks/go`

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

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

快速上手

安装

npm install payzu-pix

pip install payzu-pix

初始化 client

通过环境变量 PAYZU_TOKEN 传入 Bearer token。切勿将 token 硬编码到代码里。

import { PayZu } from 'payzu-pix';

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

PayZu facade（payzu-pix 1.0.0+）已默认指向生产环境 base URL https://api.payzu.processamento.com/v1。仅当需要指向其他 host 时，才在构造函数里传 baseUrl。

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)

安装包名为 payzu-pix，但 Python 中的 import 为 payzu_pix。host 已默认为该值，这里显式传入只是为了更清晰。

创建第一笔 Pix 收款

用上一步的 client 调用 POST /pix。仅 amount（以雷亚尔计，最小为 1）为必填。clientReference 是你的外部订单引用，同时充当幂等键。

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

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)

响应是一个 Transaction，包含 id、status、qrCodeText（复制粘贴码）、qrCodeUrl 和 qrCodeBase64。所有端点都遵循这一模式，详见 API 参考。

金额始终以**雷亚尔（BRL）**计。99.90 即 R$ 99,90。单笔收款最小金额为 R$ 1,00。

clientReference 是幂等键。重试同一笔收款时，请重发相同的 clientReference；切勿每次尝试都生成新值。这样 API 会返回已创建的收款，而不是重复创建。

完整示例

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

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;
});

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)

工作原理

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

Bug、疑问或建议

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

SDK