# Documentação

- [PayZu — Documentação](/docs): Escolha o produto PayZu que você usa
- Pix Processamento
  - [PayZu Processamento](/docs/pix-processamento): API REST de alta performance para operações Pix em produção. Cobre cobranças, saques, transferências internas e callbacks, com processamento em tempo real, 24/7.

  - **COMEÇAR**
  - [Conceitos](/docs/pix-processamento/concepts): Antes de fazer a primeira chamada, vale entender o que a API cobre, como os endpoints são agrupados e o que representa uma transação na PayZu. Esta página é o mapa mental que você vai usar em todas as outras.
  - [Primeiros passos](/docs/pix-processamento/getting-started): Em menos de 10 minutos você cria conta, gera credenciais, faz a primeira chamada autenticada e recebe um callback de teste. Este é o caminho mais curto da PayZu até a primeira transação Pix funcionando no seu sistema.
  - [Autenticação](/docs/pix-processamento/authentication): Toda chamada à PayZu Processamento usa Bearer token. Esta página mostra como enviar, onde guardar com segurança e o que fazer quando aparecer um 401 ou 403. Token é como senha, trata como tal.
  - Endpoints da API
    - [Endpoints da API](/docs/pix-processamento/endpoints): 29 endpoints da PayZu Processamento agrupados em 7 áreas funcionais. Cada endpoint tem schema completo, exemplos em curl/Node/Python/Go/PHP e try-it interativo.
    - [API Endpoints](/docs/pix-processamento/endpoints/index.en): 29 PayZu Processamento endpoints grouped into 7 functional areas. Each endpoint has complete schema, examples in curl/Node/Python/Go/PHP and interactive try-it.
    - [API Endpoints](/docs/pix-processamento/endpoints/index.zh): PayZu Processamento 的 29 个 endpoints 分为 7 个功能领域。每个 endpoint 包含完整 schema、curl/Node/Python/Go/PHP 示例和交互式 try-it。
    - Conta
      - [Conta](/docs/pix-processamento/endpoints/account): Endpoints para consultar dados da conta autenticada e saldo disponível em tempo real.
      - [Account Info](/docs/pix-processamento/endpoints/account/get_user): Account profile, permissions, limits and fee rules.
      - [Account Balance](/docs/pix-processamento/endpoints/account/get_user_balance): Available and blocked balances.
    - Callbacks
      - [Callbacks](/docs/pix-processamento/endpoints/callbacks): Inspecionar histórico de callbacks enviados, reenviar manualmente uma entrega individual ou em lote. Útil para auditoria, debug e reprocessamento de falhas.
      - [List Callbacks](/docs/pix-processamento/endpoints/callbacks/get_user_callbacks): Returns a paginated list of webhook callback logs for the user's transactions.
      - [Get Callback](/docs/pix-processamento/endpoints/callbacks/get_user_callback_by_id): Returns the details of a specific callback log.
      - [Re-send callback (single)](/docs/pix-processamento/endpoints/callbacks/resend_user_callback_single): Resend the callback of a single transaction.
      - [Re-send callbacks (bulk)](/docs/pix-processamento/endpoints/callbacks/resend_user_callbacks): Resend callbacks in bulk for transactions matching the given filters.
    - Infrações (MED)
      - [Infrações (MED)](/docs/pix-processamento/endpoints/infractions): Endpoints para lidar com disputas Pix abertas via Mecanismo Especial de Devolução (MED) do Bacen. Listar infrações, ver detalhe, submeter defesa e acompanhar histórico de defesas.
      - [List Infractions](/docs/pix-processamento/endpoints/infractions/get_infractions): List all infractions for the authenticated user with pagination and filters.
      - [Get Infraction](/docs/pix-processamento/endpoints/infractions/get_infractions_by_id): Get a specific infraction by ID.
      - [Create Defense](/docs/pix-processamento/endpoints/infractions/post_infractions_defense): Create a defense for a specific infraction.
      - [List Defenses](/docs/pix-processamento/endpoints/infractions/get_infractions_defenses): List all defenses for a specific infraction. **Requires support privileges**.
      - [Get Defense](/docs/pix-processamento/endpoints/infractions/get_infractions_defense_by_id): Get a specific defense for an infraction. **Requires support privileges**.
    - Transferência interna
      - [Transferência interna](/docs/pix-processamento/endpoints/internal-transfer): Move saldo entre duas contas PayZu sem passar pelo Pix tradicional. Liquidação instantânea, identificação por accountNumber. Ideal para repasses matriz/filial, marketplaces e payouts entre clientes PayZu.
      - [Create internal transfer](/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer): Send funds to another PayZu account using its 6-digit accountNumber. Settles instantly within PayZu.
      - [Get internal transfer](/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer): Retrieve an internal transfer by id or clientReference Use apenas um destes parâmetros: id, clientReference. Combinar mais de um retorna erro.
    - Cobranças Pix
      - [Cobranças Pix](/docs/pix-processamento/endpoints/pix-operations): Endpoints para criar cobranças Pix dinâmicas (depósitos), consultar status, renderizar QR Code e baixar comprovante.
      - [Create Charge (Pix deposit)](/docs/pix-processamento/endpoints/pix-operations/post_pix): Create a new Pix **deposit** (charge). Returns QR Code and transaction details.
      - [Retrieve Charge](/docs/pix-processamento/endpoints/pix-operations/get_pix): Get the latest status and details for a Pix **deposit (charge)**. Provide **one** of `id`, `clientReference`, or `endToEndId`. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro.
      - [Render Pix QR code (PNG)](/docs/pix-processamento/endpoints/pix-operations/get_pix_qrcode): Render the Pix QR Code of a deposit as a binary PNG image
      - [Get Transaction Receipt](/docs/pix-processamento/endpoints/pix-operations/get_proof): Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`.
    - Relatórios
      - [Relatórios](/docs/pix-processamento/endpoints/reports): Histórico de transações, relatórios assíncronos em CSV e consulta individual. Use a listagem para tela e conciliação curta, o relatório assíncrono para janelas grandes e BI.
      - [List Transactions](/docs/pix-processamento/endpoints/reports/get_user_transactions): Paginated list of account transactions with filters.
      - [List transaction details](/docs/pix-processamento/endpoints/reports/get_user_transaction_by_id): Retrieve a single transaction with its callback log and linked infractions.
      - [Generate transactions report](/docs/pix-processamento/endpoints/reports/post_user_report): Queue an asynchronous job that generates a CSV report of transactions for the given period and filters.
      - [List report jobs](/docs/pix-processamento/endpoints/reports/list_user_reports): List report jobs created by the authenticated user.
      - [List report job status](/docs/pix-processamento/endpoints/reports/get_user_report): List report jobs created by the authenticated user.
      - [Download report](/docs/pix-processamento/endpoints/reports/download_user_report): Returns a short-lived signed URL to download the CSV file.
    - Saques
      - [Saques](/docs/pix-processamento/endpoints/withdrawals): Endpoints para enviar Pix da conta PayZu para destinatários externos, por chave Pix ou por leitura de QR Code. Inclui consulta DICT, leitura de QR e download de comprovante.
      - [Create Withdrawal (Pix key)](/docs/pix-processamento/endpoints/withdrawals/post_withdraw): Send a Pix **cash out** to the specified Pix key.
      - [Retrieve Withdrawal](/docs/pix-processamento/endpoints/withdrawals/get_withdraw): Get the latest status and details for a **withdrawal**. You can provide any **one** of the following parameters: `id`, `clientReference`, or `endToEndId`. All three are optional and you can use any one of them to retrieve the withdrawal. Use apenas um destes parâmetros: id, clientReference, endToEndId. Combinar mais de um retorna erro.
      - [Create Withdrawal using QR Code](/docs/pix-processamento/endpoints/withdrawals/post_withdraw_qrcode): Cash out using a **Pix QR Code** (static/dynamic). If `amount` is not provided, the QR Code's embedded value will be used. No momento a PayZu só suporta QR Code dinâmico. QR estático ainda não é processado.
      - [Dict Pix Key Lookup](/docs/pix-processamento/endpoints/withdrawals/get_pix_key): Query the DICT (Diretório de Identificadores de Contas Transacionais) to retrieve information about a Pix key before sending a payment. Returns the key owner's details and associated financial institution.
      - [Read QR Code](/docs/pix-processamento/endpoints/withdrawals/post_pix_qrcode_read): Decode and extract information from a Pix QR Code (EMV format) before making a payment. Returns the parsed data including receiver details, amount (if present), and other QR Code metadata. No momento a PayZu só suporta QR Code dinâmico. QR estático ainda não é processado.
      - [Get Withdrawal Receipt](/docs/pix-processamento/endpoints/withdrawals/get_withdraw_proof): Retorna o comprovante da transação como JSON com o campo `base64` (PDF codificado). Decodifique pra exibir ou salvar como `.pdf`.

  - **GUIAS**
  - Tutoriais
    - [Tutoriais](/docs/pix-processamento/tutoriais): Fluxos reais de produção combinando os endpoints da PayZu Processamento, desde receber um Pix simples até lidar com uma disputa MED. Cada tutorial tem código pronto em curl, Node, Python, Go e PHP.
    - [Receber pagamento Pix](/docs/pix-processamento/tutoriais/receive-pix): Fluxo completo para receber dinheiro de um cliente via Pix. Você cria a cobrança, exibe o QR Code, processa o callback de COMPLETED e implementa polling como fallback. Código pronto em curl, Node, Python, Go e PHP.
    - [Enviar Pix](/docs/pix-processamento/tutoriais/send-pix): Dois caminhos para enviar Pix da sua conta PayZu para um destinatário externo. Saque por chave Pix (com validação DICT) ou pagar QR Code. Inclui acompanhamento de status e download de comprovante.
    - [Transferência interna](/docs/pix-processamento/tutoriais/internal-transfer): Quando origem e destino são contas PayZu, você pode mover saldo entre elas sem passar pelo Pix tradicional. Liquidação instantânea, identificação por accountNumber. Ideal para repasses internos entre matriz/filial ou pagar parceiros PayZu.
    - [Conciliação](/docs/pix-processamento/tutoriais/reconciliation): Mesmo com callbacks confiáveis, todo sistema sério bate as transações da PayZu com o banco interno diariamente. Aqui você aprende a listar transações em tempo real, gerar relatórios assíncronos para janelas grandes e usar clientReference para fechar o ciclo.
    - [Infrações (MED)](/docs/pix-processamento/tutoriais/infractions): O MED é o processo do Bacen para contestar Pix em casos de fraude ou erro do pagador. Quando uma cobrança recebida vira disputa, a PayZu cria uma infração e você tem prazo curto para responder com defesa.
  - [Webhooks](/docs/pix-processamento/webhooks): O sistema de webhooks da PayZu envia notificações em tempo real sobre mudanças de status de transações. Ao criar uma transação e fornecer um callbackUrl, atualizamos automaticamente sua aplicação a cada mudança. Inclui retry com backoff exponencial de até 72 tentativas.
  - Boas práticas
    - [Boas práticas](/docs/pix-processamento/best-practices): Padrões testados em produção que separam uma integração que dura uma semana de uma que aguenta produção. Idempotência, multi-tenant, callbacks, paginação, dinheiro, segurança, tratamento de erros e checklist final.
    - [Idempotência](/docs/pix-processamento/best-practices/idempotency): clientReference é a sua chave de idempotência e callbacks chegam mais de uma vez. Como combinar os dois para que retries não viram cobranças duplicadas nem baixas em dobro.
    - [Multi-tenant com virtualAccount](/docs/pix-processamento/best-practices/multi-tenant): Uma só conta PayZu pode atender N tenants (lojas, filiais, marketplaces) usando virtualAccount. Volta em todo callback, permite filtrar listagens e dispensa criar contas filhas.
    - [Lidando com callbacks](/docs/pix-processamento/best-practices/callbacks): Responda em menos de 5 segundos, enfileire o processamento pesado, deduplique por id + status e teste localmente com ngrok. O retry da PayZu é robusto, mas só funciona se o seu handler se comportar bem.
    - [Paginação](/docs/pix-processamento/best-practices/pagination): Endpoints de listagem (transações, callbacks, infrações) usam paginação clássica por page + limit com flag hasNextPage. Para janelas grandes prefira o relatório assíncrono em CSV.
    - [Dinheiro e precisão](/docs/pix-processamento/best-practices/money): A PayZu Pix API usa reais com casas decimais, não centavos. Como armazenar internamente sem perder precisão, converter na borda e respeitar os limites mínimos de cada operação.
    - [Segurança](/docs/pix-processamento/best-practices/security): Token Bearer é a única credencial da PayZu. Trate como senha. Esta página cobre armazenamento, rotação, mascaramento em log, proteção do webhook por IP e validação DICT antes de pagar.
    - [Consulta DICT](/docs/pix-processamento/best-practices/dict): O DICT é o banco central do Bacen que guarda todas as chaves Pix registradas no Brasil. Consultar antes de pagar valida que a chave existe, mostra o titular para confirmação e reduz pagamentos para destinatários errados.
    - [Tratamento de erros](/docs/pix-processamento/best-practices/errors): 4xx é erro seu (não retentar), 5xx é da PayZu (retry com backoff), 429 é rate limit (aguardar) e timeout exige cuidado especial porque a operação pode ter sido aplicada. Esta página tem helper de retry e estratégia de logging.
    - [Checklist de produção](/docs/pix-processamento/best-practices/checklist): Lista verificável dos itens que sua integração precisa antes de receber tráfego real. Cobre idempotência, callbacks, dinheiro, segurança, conciliação e observabilidade.

  - **SEGURANÇA**
  - [2FA (Autenticação em dois fatores)](/docs/pix-processamento/two-factor): A 2FA é obrigatória para criar tokens de API e processar saques pelo dashboard. Use qualquer app autenticador TOTP (Google Authenticator, Microsoft Authenticator, 1Password, Authy ou similar) para gerar os códigos de 6 dígitos.
  - [TrueHolder](/docs/pix-processamento/trueholder): Trava de segurança que valida a titularidade do documento (CPF/CNPJ) antes de processar a transação. Funciona tanto em cash-in (depósito) quanto em cash-out (saque), bloqueando movimentações fora do titular autorizado.
  - [MED (Mecanismo Especial de Devolução)](/docs/pix-processamento/med): Procedimento do Bacen para proteger usuários Pix em casos de fraude, golpe ou transações não autorizadas. Quando uma atividade suspeita é identificada, a instituição do pagador abre um processo formal pedindo o estorno do valor.

  - **REFERÊNCIA**
  - [Tipos de chave Pix](/docs/pix-processamento/pix-key-types): Tipos de chave Pix aceitos pela API PayZu, formato esperado de cada um e regras de validação.
  - [Glossário](/docs/pix-processamento/glossary): Termos, siglas, status e campos que aparecem na PayZu Processamento. Se você ficou travado em uma sigla do Bacen ou um campo da API, é aqui. Tudo em PT com o nome original quando relevante.
  - [SDKs](/docs/pix-processamento/sdks): SDKs oficiais PayZu Pix em Node.js, Python, Go e PHP. Gerados automaticamente do OpenAPI sempre que a API muda. Instalação via npm, pip, go get ou composer.
  - [Postman](/docs/pix-processamento/postman): Collection oficial PayZu Pix com 29 endpoints prontos pra testar no Postman. Importa com um clique, Bearer token pré-configurado e mock server para desenvolvimento sem precisar de credenciais.
  - [Para IAs (LLMs)](/docs/pix-processamento/for-ai): Toda a documentação da PayZu disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc.

  - **VISUALIZAR API**
  - [Postman](https://dev.payzu.com.br)
  - [Scalar](https://docs.payzu.com.br/api-scalar)
  - [Swagger UI](https://docs.payzu.com.br/api-swagger)
  - [OpenAPI JSON](https://docs.payzu.com.br/openapi.json)
  - [GitHub SDKs](https://github.com/PayZuPlus/payzu-sdks)
- Conta Digital

  - **COMEÇAR**
  - [Conta Digital](/docs/conta-digital): API REST completa de conta bancária digital PayZu. Pix, TED, transferências internas, cartão de crédito, gestão de saldo, extrato e webhooks em tempo real. 13 endpoints com autenticação Bearer.
  - [Primeiros passos](/docs/conta-digital/getting-started): Em menos de 10 minutos você cria conta, valida o token, faz a primeira cobrança Pix e recebe um callback de teste. Caminho mais curto da PayZu até a primeira transação na Conta Digital.
  - [Autenticação](/docs/conta-digital/authentication): Toda requisição à API Conta Digital usa Bearer Token fornecido no Dashboard PayZu. Esta página mostra como enviar, onde guardar com segurança e o que fazer quando aparecer 401 ou 403.
  - Depósitos
    - [Depósitos](/docs/conta-digital/depositos): Endpoints para criar cobranças Pix dinâmicas (entrada de dinheiro), consultar status, gerar comprovante e estornar valores recebidos.
    - [Criar Cobrança PIX](/docs/conta-digital/depositos/createPixCharge): Cria uma nova cobrança PIX para recebimento de pagamento.
    - [Consultar Transação](/docs/conta-digital/depositos/getPixTransaction): Acompanhe o status de suas transações PIX em tempo real. Consulte detalhes completos incluindo dados do pagador, valores, taxas e timestamps.
    - [Baixar Comprovante](/docs/conta-digital/depositos/getTransactionProof): Baixe comprovantes oficiais de suas transações PIX. Disponível em PDF para impressão ou Base64 para integrações automáticas.
    - [Estornar Transação](/docs/conta-digital/depositos/refundPixTransaction): Devolva valores recebidos via PIX de forma rápida e segura. O estorno é processado instantaneamente para a conta de origem.
  - Saques
    - [Saques](/docs/conta-digital/saques): Endpoints para enviar dinheiro via Pix (chave/QR/dados bancários), TED e transferência interna entre contas PayZu.
    - [Transferir via Chave PIX](/docs/conta-digital/saques/createWithdraw): Realize transferências instantâneas usando qualquer tipo de chave PIX. Suporta CPF, CNPJ, e-mail, telefone ou chaves aleatórias (EVP).
    - [Transferir via Dados Bancários](/docs/conta-digital/saques/createWithdrawBankData): Envie PIX usando dados bancários completos do destinatário. Suporta bancos tradicionais e instituições de pagamento.
    - [Transferir via TED](/docs/conta-digital/saques/createWithdrawTed): Envie dinheiro via TED (Transferência Eletrônica Disponível) para contas em outros bancos. Processamento em até 1 dia útil.
    - [Transferir via QR Code](/docs/conta-digital/saques/createWithdrawQrCode): Pague instantaneamente escaneando ou colando um QR Code PIX. Ideal para pagamentos em estabelecimentos ou transferências rápidas.
    - [Transferência Interna](/docs/conta-digital/saques/createInternalTransfer): Realiza transferências instantâneas entre contas PayZu. Ideal para movimentações entre contas da mesma plataforma, com taxas reduzidas e processamento imediato.
    - [Baixar Comprovante](/docs/conta-digital/saques/getTransactionProof): Baixe comprovantes oficiais de suas transações PIX. Disponível em PDF para impressão ou Base64 para integrações automáticas.
  - Gestão de Conta
    - [Gestão de Conta](/docs/conta-digital/gestao-de-conta): Endpoints para consultar saldo, dados da conta, extrato de transações e relatório de performance.
    - [Consultar Saldos](/docs/conta-digital/gestao-de-conta/getUserBalance): Verifique em tempo real seus saldos disponíveis, bloqueados e liberados para saque. Ideal para controle financeiro e conciliação.
    - [Informações da Conta](/docs/conta-digital/gestao-de-conta/getUser): Acesse dados completos da sua conta PayZu incluindo limites operacionais, taxas configuradas, chave PIX vinculada e permissões ativas.
    - [Extrato de Transações](/docs/conta-digital/gestao-de-conta/getUserTransactions): Acesse o histórico completo de movimentações da sua conta. Filtre por período, tipo, status ou valor. Suporta paginação e exportação.
    - [Relatório de Performance](/docs/conta-digital/gestao-de-conta/getUserSummary): Analise métricas detalhadas do seu negócio. Visualize volumes transacionados, taxas de conversão e tendências por período.

  - **GUIAS**
  - [Webhooks](/docs/conta-digital/webhooks): A API Conta Digital envia notificações via POST para o callbackUrl informado na criação de cobrança ou saque, sempre que o status da transação muda. Inclui retry com backoff de até 72 tentativas.

  - **REFERÊNCIA**
  - [Glossário](/docs/conta-digital/glossary): Status de transação, tipos de chave Pix, infrações (MED), tipos e campos comuns da API Conta Digital.
  - [Para IAs (LLMs)](/docs/conta-digital/for-ai): Toda a documentação da Conta Digital PayZu disponível em formato consumível por modelos de linguagem. Copie o conteúdo direto, baixe o dump completo, ou use as URLs específicas por página. Funciona com ChatGPT, Claude, Gemini, Cursor, Copilot, etc.

  - **VISUALIZAR API**
  - [Scalar](https://docs.payzu.com.br/api-scalar-hub)
  - [Swagger UI](https://docs.payzu.com.br/api-swagger-hub)
  - [OpenAPI JSON](https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json)
- Cartão de Crédito
  - [Cartão de Crédito](/docs/cartao): API de emissão e gestão de cartões de crédito PayZu
  - [Credit Card](/docs/cartao/index.en): PayZu credit card issuance and management API
  - [信用卡](/docs/cartao/index.zh): PayZu 信用卡发卡和管理 API
- PayZu Cell
  - [PayZu Cell](/docs/cell): API do app PayZu Cell
  - [PayZu Cell](/docs/cell/index.en): PayZu Cell app API
  - [PayZu Cell](/docs/cell/index.zh): PayZu Cell 应用的 API
- Crypto
  - [Crypto](/docs/crypto): API de operações com criptomoedas PayZu
  - [Crypto](/docs/crypto/index.en): PayZu cryptocurrency operations API
  - [Crypto](/docs/crypto/index.zh): PayZu 加密货币操作 API