pypix-api Documentation

Biblioteca em Python para comunicação com APIs bancárias focada na integração com o PIX.

Overview

pypix-api é uma biblioteca Python que simplifica a integração com APIs bancárias brasileiras para operações PIX. Atualmente suporta Banco do Brasil, Sicoob, Sicredi e Banco Inter, com planos de expansão para outros bancos.

Principais funcionalidades:

• 🏦 Bancos suportados: Banco do Brasil (001), Sicoob (756), Sicredi (748), Banco Inter (077)

• 🔐 Autenticação: OAuth2 com mTLS (PEM/PKCS#12) ou HTTP Basic (Sicredi) ou credenciais no corpo (Banco Inter)

• 💰 PIX: Cobranças imediatas, com vencimento e em lote

• 🔄 Recorrência: Pix Automático (COBR) e gestão de recorrências

• 🪝 Webhooks: Configuração e gerenciamento (Pix, COBR, REC)

• 🔍 Consultas: PIX, devoluções e locations

Quick Start

Installation

pip install pypix-api

Basic Usage

from pypix_api.auth.oauth2 import OAuth2Client
from pypix_api.banks.bb import BBPixAPI

# Configure OAuth2 authentication (token_url comes from the bank class)
oauth_client = OAuth2Client(
    token_url=BBPixAPI.TOKEN_URL,
    client_id='your-client-id',
    cert_pfx='path/to/certificate.pfx',
    pwd_pfx='cert-password',
)

# Create PIX API instance
api = BBPixAPI(oauth=oauth_client)

# Create a PIX charge
charge_data = {
    'calendario': {'expiracao': 3600},
    'devedor': {
        'cpf': '12345678901',
        'nome': 'João Silva'
    },
    'valor': {'original': '100.00'},
    'chave': 'your-pix-key',
    'solicitacaoPagador': 'Pagamento do produto X'
}

result = api.criar_cob('txid123', charge_data)
print(f"Charge created: {result}")

API Reference

Contents:

• Authentication
  • OAuth2 Client
  • mTLS Authentication
• Banks
  • Banco do Brasil
  • Sicoob
  • Sicredi
  • Banco Inter
  • Base Classes
  • PIX Methods Mixins
• Models
  • PIX Models
  • Status Enums
• Utils
  • Identificadores
  • Demais utilitários
• Scopes
  • OAuth2 Scopes Management

Authentication

class pypix_api.auth.oauth2.OAuth2Client(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False, client_secret=None, timeout=None, client_auth='basic')

Bases: object

Cliente OAuth2 para autenticação com a API

__init__(token_url, client_id=None, cert=None, pvk=None, cert_pfx=None, pwd_pfx=None, sandbox_mode=False, client_secret=None, timeout=None, client_auth='basic')

Inicializa o cliente OAuth2

Parameters:

• token_url (str) – URL de autenticação OAuth2

• client_id (str | None) – Client ID para autenticação OAuth2

• cert (str | None) – Path para o certificado PEM (opcional)

• pvk (str | None) – Path para a chave privada PEM (opcional)

• cert_pfx (str | bytes | BinaryIO | None) – Path ou dados do certificado PFX (opcional)

• pwd_pfx (str | None) – Senha do certificado PFX (opcional)

• sandbox_mode (bool) – Se True, não requer certificado (default: False)

• client_secret (str | None) – Client Secret para autenticação via HTTP Basic (opcional). Quando informado, o token é solicitado com o header Authorization: Basic base64(client_id:client_secret), como exigido por PSPs como o Sicredi. Quando omitido, mantém o fluxo padrão (client_id no corpo, autenticação de cliente via mTLS). Mantido como último parâmetro para preservar a ordem posicional histórica da assinatura.

• timeout (float | tuple[float, float] | tuple[float, None] | None) – Tempo limite da requisição de token, no formato aceito pelo requests: um número ou a tupla (conexão, leitura). None usa DEFAULT_TIMEOUT. Para leitura sem limite, use (5.0, None).

• client_auth (str) – Como o client_secret é apresentado ao PSP, quando informado. 'basic' (padrão) usa o header Authorization: Basic (Sicredi); 'body' envia client_id e client_secret no corpo do form, como exige o Banco Inter. Sem client_secret, não tem efeito.

Raises:

ValueError – Se client_auth não for 'basic' nem 'body'

get_token(scope=None)

Obtém ou renova o token de acesso para o escopo especificado

Parameters:

scope (str | None) – Escopo(s) necessário(s) para a API. Exemplos: - Cobrança por Boleto: “boletos_inclusao boletos_consulta boletos_alteracao webhooks_alteracao webhooks_consulta webhooks_inclusao” - Conta Corrente: “cco_consulta cco_transferencias openid” - Recebimento no PIX: “cob.write cob.read cobv.write cobv.read lotecobv.write lotecobv.read pix.write pix.read webhook.read webhook.write payloadlocation.write payloadlocation.read”

Returns:

Token de acesso válido para o escopo solicitado

Return type:

str

Banks

Banco do Brasil

class pypix_api.banks.bb.BBPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)

Bases: PixBBMethods, BankPixAPIBase

Implementação da API PIX do Banco do Brasil.

Parameters:

• oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

• sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API de sandbox

TOKEN_URL

URL para obtenção de token OAuth2

SCOPES

Scopes necessários para autenticação

BASE_URL: str | None = 'https://api-pix.bb.com.br/pix/v2'

SANDBOX_BASE_URL = 'https://api-pix.hm.bb.com.br/pix/v2'

TOKEN_URL: str | None = 'https://oauth.bb.com.br/oauth/token'

get_bank_code()

Return type:

str

get_base_url()

Obtém a URL base da API de acordo com o modo de operação.

Returns:

URL base da API (produção ou sandbox)

Return type:

str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

Sicoob

class pypix_api.banks.sicoob.SicoobPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)

Bases: BankPixAPIBase

Implementação da API PIX do Sicoob.

Parameters:

• oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

• sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API de sandbox

TOKEN_URL

URL para obtenção de token OAuth2

SCOPES

Scopes necessários para autenticação

BASE_URL: str | None = 'https://api.sicoob.com.br/pix/api/v2'

SANDBOX_BASE_URL = 'https://sandbox.sicoob.com.br/sicoob/sandbox/pix/api/v2'

TOKEN_URL: str | None = 'https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token'

get_bank_code()

Return type:

str

get_base_url()

Obtém a URL base da API de acordo com o modo de operação.

Returns:

URL base da API (produção ou sandbox)

Return type:

str

Note

O modo sandbox é controlado pelo parâmetro sandbox_mode passado no construtor

Sicredi

class pypix_api.banks.sicredi.SicrediPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None)

Bases: BankPixAPIBase

Implementação da API PIX do Sicredi.

Diferentemente de BB e Sicoob, a API Pix do Sicredi usa o prefixo /api com versionamento por recurso: a cobrança imediata por identificador (/cob/{txid}) está em v3, os demais recursos do Pix comum (cobv, pix, webhook, loc, lotecobv) em v2 e todo o Pix Automático (cobr, rec, locrec, solicrec, webhookcobr, webhookrec) em v1. Por isso BASE_URL aponta apenas para a raiz /api e a versão é injetada em _endpoint_url.

A autenticação exige mTLS + OAuth2 client_credentials com Authorization: Basic base64(client_id:client_secret). Passe o client_secret ao construir o OAuth2Client para ativar o fluxo Basic (ver OAuth2Client).

Parameters:

• oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

• sandbox_mode (bool) – Se True, usa ambiente de sandbox (default: False)

BASE_URL

Raiz da API de produção (sem versão)

SANDBOX_BASE_URL

Raiz da API de homologação (sem versão)

TOKEN_URL

URL para obtenção de token OAuth2 (produção)

SANDBOX_TOKEN_URL

URL para obtenção de token OAuth2 (homologação)

Note

O sandbox_mode da biblioteca usa token fixo e não faz mTLS. A homologação real do Sicredi exige mTLS + OAuth; para testá-la, use sandbox_mode=False com token_url=SicrediPixAPI.SANDBOX_TOKEN_URL e o certificado de homologação.

BASE_URL: str | None = 'https://api-pix.sicredi.com.br/api'

SANDBOX_BASE_URL = 'https://api-pix-h.sicredi.com.br/api'

TOKEN_URL: str | None = 'https://api-pix.sicredi.com.br/oauth/token'

SANDBOX_TOKEN_URL = 'https://api-pix-h.sicredi.com.br/oauth/token'

RESOURCE_VERSIONS: ClassVar[dict[str, str]] = {'cob': 'v2', 'cobr': 'v1', 'cobv': 'v2', 'loc': 'v2', 'locrec': 'v1', 'lotecobv': 'v2', 'pix': 'v2', 'rec': 'v1', 'solicrec': 'v1', 'webhook': 'v2', 'webhookcobr': 'v1', 'webhookrec': 'v1'}

RESOURCE_ITEM_VERSIONS: ClassVar[dict[str, str]] = {'cob': 'v3'}

DEFAULT_VERSION = 'v2'

get_bank_code()

Return type:

str

get_base_url()

Obtém a raiz da API (sem versão) de acordo com o modo de operação.

Returns:

Raiz da API (produção ou homologação)

Return type:

str

Banco Inter

class pypix_api.banks.inter.InterPixAPI(oauth, sandbox_mode=False, timeout=None, scopes=None, *, conta_corrente=None, homologacao=False)

Bases: PixInterMethods, BankPixAPIBase

Implementação da API PIX do Banco Inter.

Uma única versão (/pix/v2) cobre o Pix comum e o Pix Automático. A autenticação exige mTLS + OAuth2 client_credentials com client_id e client_secret no corpo do form — construa o OAuth2Client com client_secret e client_auth='body'.

Parameters:

• oauth (OAuth2Client) – Instância configurada de OAuth2Client para autenticação

• sandbox_mode (bool) – Se True, usa as URLs do Sandbox com token fixo, sem OAuth — útil só para testes locais; o Sandbox do Inter recusa o token fixo. Para o Sandbox real, use homologacao (default: False)

• timeout (float | tuple[float, float] | tuple[float, None] | None) – Tempo limite das requisições (ver BankPixAPIBase)

• scopes (str | ScopeGroup | list[str | ScopeGroup] | None) – Escopos OAuth2 a solicitar (ver BankPixAPIBase)

• conta_corrente (str | int | None) – Conta corrente da operação, enviada no header x-conta-corrente. Necessária só quando a integração estiver associada a mais de uma conta. Apenas números, incluindo o dígito; hífen, ponto, espaços e zeros à esquerda são removidos

• homologacao (bool) – Se True, usa as URLs do Sandbox do Inter com OAuth e mTLS reais — o Sandbox do Inter exige certificado e credenciais da integração de testes. Use com token_url=InterPixAPI.SANDBOX_TOKEN_URL. Libera os métodos sandbox_* (default: False)

BASE_URL

URL da API de produção

SANDBOX_BASE_URL

URL da API do Sandbox

TOKEN_URL

URL para obtenção de token OAuth2 (produção)

SANDBOX_TOKEN_URL

URL para obtenção de token OAuth2 (Sandbox)

Raises:

ValueError – Se conta_corrente não contiver um número válido

BASE_URL: str | None = 'https://cdpj.partners.bancointer.com.br/pix/v2'

SANDBOX_BASE_URL = 'https://cdpj-sandbox.partners.uatinter.co/pix/v2'

TOKEN_URL: str | None = 'https://cdpj.partners.bancointer.com.br/oauth/v2/token'

SANDBOX_TOKEN_URL = 'https://cdpj-sandbox.partners.uatinter.co/oauth/v2/token'

PARAM_TXID_CONSULTA_PIX = 'txId'

Nome do filtro de txid na query de GET /pix. A especificação do BACEN usa txid; bancos que divergem (Inter: txId) sobrescrevem.

__init__(oauth, sandbox_mode=False, timeout=None, scopes=None, *, conta_corrente=None, homologacao=False)

conta_corrente: str | None

homologacao: bool

get_bank_code()

Return type:

str

get_base_url()

Obtém a URL base da API de acordo com o modo de operação.

Returns:

URL base da API (produção ou Sandbox)

Return type:

str

listar_webhooks(inicio, fim, pagina_atual=0, itens_por_pagina=100)

Não suportado: o Inter não oferece GET /webhook.

Raises:

NotImplementedError – Sempre. Use consultar_webhook(chave)

Return type:

dict[str, Any]

Examples

Examples:

• Banco do Brasil - Exemplos Básicos
  • Configuração Inicial
  • Configuração Básica
  • Criando uma Cobrança Imediata
  • Exemplo Completo
  • Variáveis de Ambiente
• Sicoob - Exemplos Básicos
  • Configuração Inicial
  • Configuração Básica
  • Criando uma Cobrança Simples
  • Exemplo Completo
  • Variáveis de Ambiente
• Sicredi - Exemplos Básicos
  • Configuração Inicial
  • Configuração Básica
  • Criando uma Cobrança Simples
  • Exemplo Completo
  • Variáveis de Ambiente
• Configuração de Webhooks
  • Configuração Básica
  • Servidor Flask para Webhooks
  • Gerenciamento de Webhooks
  • Testando Webhooks Localmente
• Cobranças com Vencimento
  • Cobrança com Vencimento Simples
  • Cobrança Recorrente Mensal
  • Exemplo de Uso
  • Monitoramento de Cobranças
  • Script Completo
• Pix Automático (Recorrência)
  • Status disponíveis
  • Fluxo completo
  • O identificador da recorrência (idRec)
  • Cancelar uma cobrança sem cancelar a recorrência
  • Consultar o status
  • Retentativa
• Tratamento Avancado de Erros
  • Configuracao Basica de Observabilidade
  • Tipos de Erro Especializados
  • Tratamento com Context Manager
  • Tratamento com Decorators
  • Exemplo Completo com Banco do Brasil
  • Health Check e Monitoramento
  • Configuracao para Producao
  • Integracao com Sistemas de Monitoramento
  • Próximos Passos

Contributing

See our Contributing Guide for information on how to contribute to this project.

Security

For security vulnerabilities, please see our Security Policy.

Changelog

See the Changelog for a detailed history of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Indices and tables

• Index

• Module Index

• Search Page