PayZu Docs

Official Node, Python and Go libraries so you integrate without hand-rolling requests: install via npm, pip or go get, pass your token, and create your first charge in minutes, fully typed.

npm payzu-pix PyPI payzu-pix SDKs repo API reference

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` on npm	`npm install payzu-pix`
Python	`payzu-pix` on PyPI	`pip install payzu-pix`
Go	`payzu-sdks/go` module	`go get github.com/PayZuAI/payzu-sdks/go`

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.

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

Install

npm install payzu-pix

pip install payzu-pix

Initialize the client

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

import { PayZu } from 'payzu-pix';

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

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.

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)

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.

Create your first Pix charge

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

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)

The response is a Transaction with id, status, qrCodeText (copy-and-paste), qrCodeUrl and qrCodeBase64. Every endpoint follows this pattern, see the API reference.

Amounts are always in reais (BRL). 99.90 is R$ 99.90. The minimum charge is R$ 1.00.

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.

Full example

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

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)

How they work

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

Bug, question or suggestion

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

SDKs