Glossary

Stuck on a Bacen acronym or a field that came back in the response? Here are the terms, statuses, and codes that show up in day-to-day integration, explained in English.

API Reference Webhooks MED Pix key types

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`)

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`)

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`)

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`)

Value	Meaning
`PENDING`	Refund in processing queue.
`COMPLETED`	Refund processed, amount returned.
`CANCELED`	Refund canceled before completion.

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.

Infraction / MED

Status (`infraction.status`)

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`)

Value	Description
`REFUND_REQUEST`	Standard refund request.
`FRAUD`	Security-related complaint.
`REFUND_CANCELLED`	Cancellation of a previous refund.

Analysis result (`infraction.analysisResult`)

Value	Description
`AGREED`	Infraction accepted. Refund will be processed.
`DISAGREED`	Infraction rejected. No refund, transaction maintained.

Reported by (`infraction.reportedBy`)

Value	Description
`DEBITED_PARTICIPANT`	Payer's institution opened it.
`CREDITED_PARTICIPANT`	Receiver's institution opened it.

Common API fields

We keep the English names because that's how they go in the JSON.

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.
`accountNumber`	PayZu account number (6 digits). Identifies the account in internal transfers and in the transaction payload.

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

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 `<img>`.
`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

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

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

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

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

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

The full list of HTTP codes and how to react to each is in Error codes.

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

Error codes Tutorials

Glossary

On this page