Glossary

API Reference Webhooks MED Pix key types

General concepts

Term	Definition
Pix	Instant payment system from the Central Bank of Brazil. Runs 24/7, settlement in seconds.
DICT	Directory of Transactional Account Identifiers. Bacen's 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 that start with `00020126...`.
Dynamic QR	QR Code with `id` and (optionally) amount per charge. The only one supported by Magen.
Static QR	Reusable QR Code. Not supported by Magen.
MED	Special Refund Mechanism. Bacen process to contest a Pix in case of fraud or error. Becomes an infraction in Magen.
Bearer token	Authentication token sent in the `Authorization: Bearer YOUR_TOKEN` header. Magen's only auth method.
Callback / Webhook	`POST` that Magen sends to your `callbackUrl` when a transaction changes status. Retries up to 72 attempts with backoff.
Idempotency	Guarantee that executing the same operation multiple times has the same effect as executing it once. Use `clientReference` on creation.
Exponential backoff	Retry strategy where the interval between attempts doubles (1s, 2s, 4s, 8s). Used by Magen and recommended on your retries for `5xx`/`429`.
Jitter	Random variation added to backoff to avoid "thundering herd" (clients hitting all at once).

Transaction types (`type`)

Value	What it is
`DEPOSIT`	Pix charge, money coming into your account.
`WITHDRAW`	Pix withdrawal, money going out to a Pix key or QR Code.
`INTERNAL_TRANSFER`	Transfer between Magen accounts, instant.
`COMMISSION`	Commission entry (internal use). May appear in listings and reports.

Transaction status (`status`)

The status varies by type. Full list:

Status	Meaning
`PENDING`	Awaiting payment (charge) or processing (withdrawal/transfer).
`COMPLETED`	Completed successfully. On deposit: customer paid. On withdrawal: money left the account.
`CANCELED`	Canceled before completion (manual or by rule).
`WAITING_FOR_REFUND`	Awaiting refund processing (usually after MED accepted).
`REFUNDED`	Refunded, amount returned to the payer.
`EXPIRED`	Charge expired without payment (passed `expiresIn`).
`ERROR`	Technical error during the operation. See `cancellationReason` in the payload.

Refund status (`refundStatus`)

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

Pix key types (`pixType`)

Value	What it is
`cpf`	Recipient's CPF (11 digits).
`cnpj`	Recipient's CNPJ (14 digits).
`phone`	Phone with country/area code in `+5511999999999` format.
`email`	Email address registered at Bacen.
`evp`	Random key (UUID generated by the bank).

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 a 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`	Recipient's institution opened it.

Common API fields

We keep the English name because that's how they appear in the JSON.

Identification

Field	What it's for
`id`	Unique transaction identifier in Magen. Format `MAGEN` + timestamp + hash.
`clientReference`	External identifier that you define. Returns in every callback. Maximum 64 characters.
`virtualAccount`	Virtual sub-account (up to 50 chars) for multi-tenant (stores, branches, marketplaces). Returns in the callback.
`endToEndId`	Unique operation identifier at Bacen. Format `E` + 32 characters. Useful in disputes.
`requestId`	Unique call ID at Magen. Appears in every error response (4xx and 5xx). Always log it and send it when opening support, investigation traces directly. See Error format.
`accountNumber`	Magen account number (6 digits). Used in internal transfers.

Amounts

Field	What it's for
`amount`	Amount in reais (BRL), not cents. E.g.: `10.90` is R$ 10.90.
`serviceFeeCharged`	Fee charged by Magen 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. Maximum 172000 (47h).

Payer

Campo	What it's for
`payerName`	Payer's name (comes 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 Magen account (present in internal transfers).

Recipient

Field	What it's for
`receiverName`	Recipient's name (in withdrawals).
`receiverDocument`	Recipient's CPF/CNPJ.
`receiverInstitutionIspb`	ISPB of the recipient's bank.
`receiverInstitutionName`	Recipient's bank name.
`receiverAccountNumber`	Recipient's Magen account (in internal transfers).

Withdrawal 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 withdrawal (in the callback).
`withdrawPixType`	Type of key used in the withdrawal.

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

Other

Field	What it's for
`callbackUrl`	URL where Magen posts transaction updates.
`description`	Free text up to 140 characters (used in withdrawal and internal transfer).
`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

Code	What it means
`200`	Operation successful.
`201`	Resource created (charge, withdrawal, transfer).
`204`	Success with no response body.
`400`	Invalid payload. See `message` for details.
`401`	Token missing, invalid, or revoked.
`403`	Valid token but no permission for the endpoint.
`404`	Resource not found.
`409`	Conflict (duplicate, resource in invalid state).
`422`	Semantic validation failed.
`429`	Rate limit reached. Wait and retry with backoff.
`5xx`	Server error. Retry with exponential backoff (`5xx` and `429` only).

Additional acronyms (Bacen / Pix)

Acronym	Expansion
Bacen	Central Bank of Brazil.
PSP	Payment Service Provider. Each bank/fintech is a PSP.
ISPB	Brazilian Payment System Identifier. 8-digit code that identifies each PSP.
SPI	Instant Payment System. Bacen's infrastructure that processes Pix.
CACC	Checking account (ISO 20022 naming used by Bacen).
SVGS	Savings account.
TRAN	Payment account (transitional).
CUID	Unique string identifier used by Magen in internal resources (e.g.: infraction `id`).

Tipos de chave Pix

Tipos de chave Pix aceitos pela API Magen, formato esperado de cada um e regras de validação.

Para IAs (LLMs)

Toda a documentação da Magen 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.