# Concepts (/en/docs/pix-processamento/concepts)

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

  <QuickLink href="/docs/pix-processamento/endpoints" title="API reference" />

  <QuickLink href="/docs/pix-processamento/glossary" title="Glossary" />

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

## Overview [#overview]

PayZu Processamento is a REST API with endpoints split across functional groups. All communication happens in JSON, over HTTPS, with Bearer token. Monetary values are always in &#x2A;*reais (BRL)**.

<Mermaid
  chart="`
flowchart LR
  App[&#x22;Your application&#x22;] -->|&#x22;Bearer token&#x22;| API[&#x22;PayZu API&#x22;]
  API --> PIX[&#x22;Pix charges&#x22;]
  API --> REF[&#x22;Refunds&#x22;]
  API --> WD[&#x22;Pix Payments&#x22;]
  API --> IT[&#x22;Internal transfer&#x22;]
  API --> ACC[&#x22;Account&#x22;]
  API --> REP[&#x22;Reports&#x22;]
  API --> CB[&#x22;Callbacks&#x22;]
  API --> WH[&#x22;Webhooks&#x22;]
  API --> MED[&#x22;Infractions (MED)&#x22;]

  click PIX &#x22;/en/docs/pix-processamento/endpoints/pix-operations/post_pix&#x22; &#x22;Pix charge endpoints&#x22;
  click REF &#x22;/en/docs/pix-processamento/endpoints/refunds/post_refund&#x22; &#x22;Refund endpoints&#x22;
  click WD &#x22;/en/docs/pix-processamento/endpoints/withdrawals/post_withdraw&#x22; &#x22;Withdrawal endpoints&#x22;
  click IT &#x22;/en/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer&#x22; &#x22;Internal transfer endpoints&#x22;
  click ACC &#x22;/en/docs/pix-processamento/endpoints/account/get_user&#x22; &#x22;Account endpoints&#x22;
  click REP &#x22;/en/docs/pix-processamento/endpoints/reports/get_user_transactions&#x22; &#x22;Report endpoints&#x22;
  click CB &#x22;/en/docs/pix-processamento/endpoints/callbacks/get_user_callbacks&#x22; &#x22;Callback endpoints&#x22;
  click WH &#x22;/en/docs/pix-processamento/endpoints/webhooks/post_user_webhook&#x22; &#x22;Webhook endpoints&#x22;
  click MED &#x22;/en/docs/pix-processamento/endpoints/infractions/get_infractions&#x22; &#x22;Infraction endpoints&#x22;

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

## Endpoint groups [#endpoint-groups]

The full inventory of groups, with the endpoints in each one, lives in the API reference.

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

## Transaction model [#transaction-model]

Every movement at PayZu is represented by a **transaction**. Whether it's a charge, Pix payment or internal transfer, the basic structure is the same.

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

  D --> D1[&#x22;Receives Pix from a third party&#x22;]
  W --> W1[&#x22;Sends Pix by key or QR&#x22;]
  I --> I1[&#x22;Moves balance between PayZu accounts<br/>two legs: WITHDRAW and DEPOSIT&#x22;]

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

### Main fields [#main-fields]

| Field             | Type   | Purpose                                                                                        |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `id`              | string | Unique identifier of the transaction at PayZu.                                                 |
| `type`            | string | `DEPOSIT`, `WITHDRAW` or `COMMISSION`.                                                         |
| `method`          | string | `PIX`, `BANK_SLIP` or `INTERNAL_TRANSFER`.                                                     |
| `status`          | string | Current state. The most common ones: `PENDING`, `COMPLETED`, `REFUNDED`, `EXPIRED`, `ERROR`.   |
| `amount`          | number | Value in &#x2A;*reais (BRL)**. E.g.: `10.90` is R$ 10.90.                                      |
| `clientReference` | string | **Your** external identifier. Returns in every callback. Use it for idempotência and lookup.   |
| `virtualAccount`  | string | Virtual subaccount (up to 50 chars). Use it for multi-tenant (stores, branches, marketplaces). |
| `callbackUrl`     | string | URL to receive status updates via webhook.                                                     |
| `endToEndId`      | string | Unique identifier of the operation at Bacen. Useful for tracking in disputes.                  |

All fields detailed in the [Glossary](/docs/pix-processamento/glossary#common-api-fields).

## Typical lifecycle [#typical-lifecycle]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;You create<br>POST /pix or /withdraw&#x22;] --> B[&#x22;Transaction PENDING&#x22;]
  B --> C{&#x22;Payment processed?&#x22;}
  C -->|Yes| D[&#x22;COMPLETED&#x22;]
  C -->|Expires| E[&#x22;EXPIRED&#x22;]
  C -->|Error| F[&#x22;ERROR&#x22;]
  D -.->|MED dispute| G[&#x22;REFUNDED&#x22;]

  click G &#x22;/en/docs/pix-processamento/med&#x22; &#x22;MED, Special Refund Mechanism&#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
`"
/>

Full states by type in each endpoint reference. Quick table in the [Glossary · Transaction status](/docs/pix-processamento/glossary#status-de-transação-status).

## API conventions [#api-conventions]

| Item           | Value                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| Base URL       | `https://api.payzu.processamento.com/v1`                                                                       |
| Authentication | `Authorization: Bearer YOUR_TOKEN`                                                                             |
| Content-Type   | `application/json` (required on every call)                                                                    |
| Values         | In reais (BRL), never in cents                                                                                 |
| Dates          | ISO 8601 (`2026-08-11T10:46:26.986Z`)                                                                          |
| Encoding       | UTF-8                                                                                                          |
| Pagination     | `page` + `limit`; the envelope varies per route ([details](/docs/pix-processamento/best-practices/pagination)) |
| Webhooks       | `POST` to `callbackUrl`, retry up to 40x                                                                       |

## Next steps [#next-steps]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/authentication" title="Bearer authentication" />

  <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 (Pix dispute)" />

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

  <QuickLink href="/docs/pix-processamento/glossary" title="Full glossary" />
</QuickLinks>