# Conceitos (/docs/pix-processamento/concepts)



<QuickLinks>
  <QuickLink href="/docs/pix-processamento/getting-started" title="Primeiros passos" />

  <QuickLink href="/docs/pix-processamento/endpoints" title="Referência da API" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossário" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />
</QuickLinks>

## Visão geral [#visão-geral]

A PayZu Processamento é uma API REST com endpoints divididos em grupos funcionais. Toda a comunicação acontece em JSON, sobre HTTPS, com Bearer token. Valores monetários estão sempre em &#x2A;*reais (BRL)**.

<Mermaid
  chart="`
flowchart LR
  App[&#x22;Sua aplicação&#x22;] -->|&#x22;Bearer token&#x22;| API[&#x22;API PayZu&#x22;]
  API --> PIX[&#x22;Cobranças Pix&#x22;]
  API --> REF[&#x22;Estornos&#x22;]
  API --> WD[&#x22;Saques&#x22;]
  API --> IT[&#x22;Transferência interna&#x22;]
  API --> ACC[&#x22;Conta&#x22;]
  API --> REP[&#x22;Relatórios&#x22;]
  API --> CB[&#x22;Callbacks&#x22;]
  API --> WH[&#x22;Webhooks&#x22;]
  API --> MED[&#x22;Infrações (MED)&#x22;]

  click PIX &#x22;/docs/pix-processamento/endpoints/pix-operations&#x22; &#x22;Endpoints de cobrança Pix&#x22;
  click REF &#x22;/docs/pix-processamento/endpoints/refunds&#x22; &#x22;Endpoints de estorno&#x22;
  click WD &#x22;/docs/pix-processamento/endpoints/withdrawals&#x22; &#x22;Endpoints de saque&#x22;
  click IT &#x22;/docs/pix-processamento/endpoints/internal-transfer&#x22; &#x22;Endpoints de transferência interna&#x22;
  click ACC &#x22;/docs/pix-processamento/endpoints/account&#x22; &#x22;Endpoints de conta&#x22;
  click REP &#x22;/docs/pix-processamento/endpoints/reports&#x22; &#x22;Endpoints de relatórios&#x22;
  click CB &#x22;/docs/pix-processamento/endpoints/callbacks&#x22; &#x22;Endpoints de callbacks&#x22;
  click WH &#x22;/docs/pix-processamento/endpoints/webhooks&#x22; &#x22;Endpoints de webhooks&#x22;
  click MED &#x22;/docs/pix-processamento/endpoints/infractions&#x22; &#x22;Endpoints de infrações&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Grupos de endpoints [#grupos-de-endpoints]

O inventário completo dos grupos, com os endpoints de cada um, está na referência da API.

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints" title="Endpoints da API" />
</QuickLinks>

## Modelo de transação [#modelo-de-transação]

Toda movimentação na PayZu é representada por uma **transação**. Independente de ser cobrança, saque ou transferência interna, a estrutura básica é a mesma.

<Mermaid
  chart="`
flowchart TD
  T[&#x22;Transação&#x22;]
  T --> D[&#x22;type DEPOSIT&#x22;]
  T --> W[&#x22;type WITHDRAW&#x22;]
  T --> I[&#x22;method INTERNAL_TRANSFER&#x22;]

  D --> D1[&#x22;Recebe Pix de terceiro&#x22;]
  W --> W1[&#x22;Envia Pix por chave ou QR&#x22;]
  I --> I1[&#x22;Move saldo entre contas PayZu<br/>duas pernas: WITHDRAW e DEPOSIT&#x22;]

  click D &#x22;/docs/pix-processamento/endpoints/pix-operations&#x22; &#x22;Endpoints DEPOSIT&#x22;
  click W &#x22;/docs/pix-processamento/endpoints/withdrawals&#x22; &#x22;Endpoints WITHDRAW&#x22;
  click I &#x22;/docs/pix-processamento/endpoints/internal-transfer&#x22; &#x22;Endpoints INTERNAL_TRANSFER&#x22;
  click D1 &#x22;/docs/pix-processamento/tutoriais/receive-pix&#x22; &#x22;Tutorial Receber Pix&#x22;
  click W1 &#x22;/docs/pix-processamento/tutoriais/send-pix&#x22; &#x22;Tutorial Enviar Pix&#x22;
  click I1 &#x22;/docs/pix-processamento/tutoriais/internal-transfer&#x22; &#x22;Tutorial Transferência interna&#x22;

  style T fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

### Campos principais [#campos-principais]

| Campo             | Tipo   | Para que serve                                                                         |
| ----------------- | ------ | -------------------------------------------------------------------------------------- |
| `id`              | string | Identificador único da transação na PayZu.                                             |
| `type`            | string | `DEPOSIT`, `WITHDRAW` ou `COMMISSION`.                                                 |
| `method`          | string | `PIX`, `BANK_SLIP` ou `INTERNAL_TRANSFER`.                                             |
| `status`          | string | Estado atual. Os mais comuns: `PENDING`, `COMPLETED`, `REFUNDED`, `EXPIRED`, `ERROR`.  |
| `amount`          | number | Valor em &#x2A;*reais (BRL)**. Ex: `10.90` é R$ 10,90.                                 |
| `clientReference` | string | **Seu** identificador externo. Volta em todo callback. Use para idempotência e lookup. |
| `virtualAccount`  | string | Subconta virtual (até 50 chars). Use para multi-tenant (lojas, filiais, marketplaces). |
| `callbackUrl`     | string | URL para receber atualizações de status via webhook.                                   |
| `endToEndId`      | string | Identificador único da operação no Bacen. Útil para rastrear em disputas.              |

Todos os campos detalhados no [Glossário](/docs/pix-processamento/glossary#campos-comuns-da-api).

## Ciclo de vida típico [#ciclo-de-vida-típico]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Você cria<br>POST /pix ou /withdraw&#x22;] --> B[&#x22;Transação PENDING&#x22;]
  B --> C{&#x22;Pagamento processado?&#x22;}
  C -->|Sim| D[&#x22;COMPLETED&#x22;]
  C -->|Expira| E[&#x22;EXPIRED&#x22;]
  C -->|Erro| F[&#x22;ERROR&#x22;]
  D -.->|Disputa MED| G[&#x22;REFUNDED&#x22;]

  click G &#x22;/docs/pix-processamento/med&#x22; &#x22;MED, Mecanismo Especial de Devolução&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
  style G fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

Estados completos por tipo na referência de cada endpoint. Tabela rápida no [Glossário · Status de transação](/docs/pix-processamento/glossary#status-de-transação-status).

## Convenções da API [#convenções-da-api]

| Item         | Valor                                            |
| ------------ | ------------------------------------------------ |
| Base URL     | `https://api.payzu.processamento.com/v1`         |
| Autenticação | `Authorization: Bearer SEU_TOKEN`                |
| Content-Type | `application/json` (obrigatório em toda chamada) |
| Valores      | Em reais (BRL), nunca em centavos                |
| Datas        | ISO 8601 (`2025-11-23T10:46:26.986Z`)            |
| Encoding     | UTF-8                                            |
| Paginação    | `page` + `limit` com flag `hasNextPage`          |
| Webhooks     | `POST` em `callbackUrl`, retry até 72x           |

## Próximos passos [#próximos-passos]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/authentication" title="Autenticação Bearer" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks (callbacks)" />

  <QuickLink href="/docs/pix-processamento/best-practices/idempotency" title="Idempotência" />

  <QuickLink href="/docs/pix-processamento/med" title="MED (disputa Pix)" />

  <QuickLink href="/docs/pix-processamento/pix-key-types" title="Tipos de chave Pix" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossário completo" />
</QuickLinks>