SDKs

Bibliotecas oficiais em Node e Python pra você integrar sem montar requisição na mão: instala pelo npm ou pip, passa o token e cria a primeira cobrança em minutos, com tudo tipado.

npm payzu-pix PyPI payzu-pix Repo dos SDKs Referência da API

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` no npm	`npm install payzu-pix`
Python	`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

Instalar

npm install payzu-pix

pip install payzu-pix

Inicializar o client

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

import { PayZu } from 'payzu-pix';

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

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.

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)

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.

Criar a primeira cobrança Pix

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

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

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)

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.

Valores sempre em reais (BRL). 99.90 é R$ 99,90. O valor mínimo de uma cobrança é R$ 1,00.

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.

Exemplo completo

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

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

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)

Como funcionam

O workflow Generate SDKs (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

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