# Glossary (/en/docs/pix-processamento/glossary)
## General concepts [#general-concepts]
| Term | Definition |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Pix** | Brazilian Central Bank's instant payment system. Runs 24/7, settlement in seconds. |
| **DICT** | Directory of Transactional Account Identifiers. Bacen database that maps Pix key → account. Query it before paying. |
| **EMV / BR Code** | International standard used by Pix to generate copy-and-paste QR Codes. Strings starting with `00020126...`. |
| **Dynamic QR** | QR Code with `id` and (optionally) amount per charge. |
| **Static QR** | Reusable QR Code, the same code for multiple payments. |
| **MED** | Special Return Mechanism. Bacen process to dispute a Pix in case of fraud or error. Becomes an **infraction** at PayZu. |
| **Bearer token** | Authentication token sent in the `Authorization: Bearer YOUR_TOKEN` header. PayZu's only auth method. |
| **Callback / Webhook** | `POST` that PayZu sends to your `callbackUrl` when a transaction changes status. Retries up to 40 times with backoff. |
| **Idempotency** | Guarantee that running the same operation multiple times has the same effect as running it once. Use `clientReference` on creation. |
| **Exponential backoff** | Retry strategy where the interval between attempts doubles (1s, 2s, 4s, 8s). Used by PayZu and recommended for your retry on `5xx`/`429`. |
| **Jitter** | Random variation added to backoff to avoid the "thundering herd" (clients all hitting at once). |
## Transaction types (`type`) [#transaction-types-type]
| Value | What it is |
| ------------ | ----------------------------------------------------------------------------- |
| `DEPOSIT` | Pix charge, money coming into your account. |
| `WITHDRAW` | Pix payment, money going out to a Pix key or QR Code. |
| `COMMISSION` | Commission entry credited to the account. May appear in listings and reports. |
## Transaction method (`method`) [#transaction-method-method]
| Value | What it is |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `PIX` | Operation settled via Pix. |
| `BANK_SLIP` | Operation via bank slip (boleto). |
| `INTERNAL_TRANSFER` | Transfer between PayZu accounts, instant. Each leg arrives with `type` `WITHDRAW` (payer) or `DEPOSIT` (receiver). |
## Transaction status (`status`) [#transaction-status-status]
Status varies by type. Full list:
| Status | Meaning |
| -------------------- | ---------------------------------------------------------------------------------- |
| `PENDING` | Awaiting payment (charge) or processing (Pix payment). |
| `COMPLETED` | Successfully completed. On deposit: customer paid. On Pix payment: money went out. |
| `CANCELED` | Canceled before completion (manually or by rule). |
| `WAITING_FOR_REFUND` | Awaiting refund processing (usually after an accepted MED). |
| `REFUNDED` | Refunded, amount returned to the payer. |
| `EXPIRED` | Charge expired without payment (past `expiresIn`). |
| `ERROR` | Technical error during the operation. See `cancellationReason` in the payload. |
## Refund status (`refundStatus`) [#refund-status-refundstatus]
| Value | Meaning |
| ----------- | ---------------------------------- |
| `PENDING` | Refund in processing queue. |
| `COMPLETED` | Refund processed, amount returned. |
| `CANCELED` | Refund canceled before completion. |
## Pix key types (`pixType`) [#pix-key-types-pixtype]
The five key types (`cpf`, `cnpj`, `phone`, `email`, `evp`), with the format and an example of each, are in [Pix key types](/docs/pix-processamento/pix-key-types).
## Infraction / MED [#infraction--med]
### Status (`infraction.status`) [#status-infractionstatus]
| Value | Description |
| --------------------- | ---------------------------------------------------- |
| `WAITING_PSP` | Awaiting provider response. |
| `OPEN` | Infraction active and under analysis. |
| `ACKNOWLEDGED` | Acknowledged by the institution. |
| `DEFENDED` | Defense has been submitted. |
| `ANSWERED` | Additional information provided. |
| `WAITING_ADJUSTMENTS` | Awaiting documentation. |
| `CLOSED` | Resolved with final decision (see `analysisResult`). |
| `CANCELLED` | Canceled before resolution. |
### Type (`infraction.type`) [#type-infractiontype]
| Value | Description |
| ------------------ | ---------------------------------- |
| `REFUND_REQUEST` | Standard refund request. |
| `FRAUD` | Security-related complaint. |
| `REFUND_CANCELLED` | Cancellation of a previous refund. |
### Analysis result (`infraction.analysisResult`) [#analysis-result-infractionanalysisresult]
| Value | Description |
| ----------- | ------------------------------------------------------- |
| `AGREED` | Infraction accepted. Refund will be processed. |
| `DISAGREED` | Infraction rejected. No refund, transaction maintained. |
### Reported by (`infraction.reportedBy`) [#reported-by-infractionreportedby]
| Value | Description |
| ---------------------- | --------------------------------- |
| `DEBITED_PARTICIPANT` | Payer's institution opened it. |
| `CREDITED_PARTICIPANT` | Receiver's institution opened it. |
## Common API fields [#common-api-fields]
We keep the English names because that's how they go in the JSON.
### Identification [#identification]
| Field | What it's for |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Unique transaction identifier at PayZu. Environment prefix + UTC date (`YYYYMMDD`) + random segment + 6 digits derived from the account. Treat as opaque: to date or sort, use `createdAt` and `paidAt`, never slice the `id`. |
| `clientReference` | External identifier that **you** define. Comes back in every callback. Max 64 characters. |
| `virtualAccount` | Virtual subaccount (up to 50 chars) for multi-tenant (stores, branches, marketplaces). Returned in the callback. |
| `endToEndId` | Unique identifier of the operation at Bacen. Format `E` + 32 characters. Useful in disputes. |
| `requestId` | **Unique ID of the call at PayZu**. Appears in **every error response** (4xx and 5xx). Always log and send it when opening support, investigation traces directly. See [Error format](/docs/pix-processamento/authentication#formato-de-erro). |
| `accountNumber` | PayZu account number (6 digits). Identifies the account in internal transfers and in the transaction payload. |
### Amounts [#amounts]
| Field | What it's for |
| ------------------- | ------------------------------------------------------- |
| `amount` | Value in **reais (BRL)**. Ex: `10.90` is R$ 10.90. |
| `serviceFeeCharged` | Fee charged by PayZu on the operation, in reais. |
### Generated charge [#generated-charge]
| Field | What it's for |
| ------------------- | -------------------------------------------------------------------------- |
| `qrCodeText` | Pix copy-and-paste code (EMV BR Code). Use in an input with a copy button. |
| `qrCodeUrl` | Public URL that renders the QR as PNG. Use directly in `![]()
`. |
| `qrCodeBase64` | QR Code image in Base64. |
| `generatedName` | Reference name associated with the charge. |
| `generatedDocument` | CPF or CNPJ associated with the charge. |
| `generatedEmail` | Email linked to the charge. |
| `expiresIn` | Charge expiration time in seconds. Max 172000 (47h). |
### Payer [#payer]
| Field | What it's for |
| ---------------------- | --------------------------------------------------------------- |
| `payerName` | Payer's name (arrives in the callback after payment). |
| `payerDocument` | Payer's CPF/CNPJ. |
| `payerInstitutionIspb` | ISPB of the payer's bank (8 digits). |
| `payerInstitutionName` | Payer's bank name. |
| `payerAccountNumber` | Payer's PayZu account (in Pix payments and internal transfers). |
### Receiver [#receiver]
| Field | What it's for |
| ------------------------- | --------------------------------------------------------------- |
| `receiverName` | Recipient's name (in Pix payments). |
| `receiverDocument` | Recipient's CPF/CNPJ. |
| `receiverInstitutionIspb` | ISPB of the recipient's bank. |
| `receiverInstitutionName` | Recipient's bank name. |
| `receiverAccountNumber` | Recipient's PayZu account (in deposits and internal transfers). |
### Pix payment by key [#pix-payment-by-key]
| Field | What it's for |
| ----------------- | ------------------------------------------------- |
| `pixKey` | Recipient's Pix key. Format depends on `pixType`. |
| `pixType` | Key type: `cpf`, `cnpj`, `phone`, `email`, `evp`. |
| `withdrawPixKey` | Key used in the Pix payment (in the callback). |
| `withdrawPixType` | Type of the key used in the Pix payment. |
### Settlement and refund [#settlement-and-refund]
| Field | What it's for |
| -------------------- | -------------------------------------------------------- |
| `paidAt` | Payment timestamp (ISO 8601). Present after `COMPLETED`. |
| `cancellationReason` | Cancellation reason. |
| `refundEndToEndId` | EndToEnd ID of the refund. |
| `refundAmount` | Refunded amount. |
| `refundStatus` | Refund status: `PENDING`, `COMPLETED`, `CANCELED`. |
| `refundReason` | Refund reason. |
| `refundDescription` | Refund description. |
| `refundedAt` | Refund timestamp (ISO 8601). |
### Others [#others]
| Field | What it's for |
| ------------- | --------------------------------------------------------------------------- |
| `callbackUrl` | URL where PayZu posts transaction updates. |
| `description` | Free text for the transaction; on internal transfers, up to 500 characters. |
| `createdAt` | Transaction creation timestamp (ISO 8601). |
| `updatedAt` | Last update (ISO 8601). |
| `infraction` | Object present in the callback when the transaction becomes a MED dispute. |
## HTTP codes [#http-codes]
The full list of HTTP codes and how to react to each is in [Error codes](/docs/pix-processamento/error-codes).
## Additional acronyms (Bacen / Pix) [#additional-acronyms-bacen--pix]
| Acronym | Expansion |
| --------- | ------------------------------------------------------------------------------------ |
| **Bacen** | Brazilian Central Bank. |
| **PSP** | Payment Services Provider. Each bank/fintech is a PSP. |
| **ISPB** | Brazilian Payment System Identifier. 8-digit code that identifies each PSP. |
| **SPI** | Instant Payment System. The Bacen infrastructure that processes Pix. |
| **CACC** | Checking account (ISO 20022 nomenclature used by Bacen). |
| **SVGS** | Savings account. |
| **TRAN** | Payment account (transitional). |
| **CUID** | Unique string identifier used by PayZu in internal resources (e.g. infraction `id`). |
## Next steps [#next-steps]