Webhook Payloads

Examples of the payloads sent for each event type. All webhooks are sent as HTTP POST with Content-Type: application/json.

Security headers

Each notification includes the headers X-Minha Konta-Signature (HMAC-SHA256), X-Minha Konta-Timestamp, X-Minha Konta-Event-Id, and X-Minha Konta-Event-Type. See Webhooks - Overview for details on validation.

---

Status Reference

Not every event means the transaction is complete. Use the table below to know when money has actually been settled.

Event	Status	Meaning	Money settled?
pix.charge.created	created	QR code generated or cash-in initiated. Awaiting payment.	No - only created
pix.charge.paid	paid	PIX received and settled in the account. Balance updated, fee charged.	Yes
pix.charge.expired	expired	QR code expired without payment.	N/A
pix.charge.cancelled	cancelled	QR code explicitly cancelled by the merchant before payment.	N/A
pix.payout.queued	queued	PIX send waiting for automatic reprocessing due to DICT limit. No debit yet.	No -- awaiting availability
pix.payout.processing	processing	PIX sent, awaiting destination confirmation. Balance on hold.	No - may reverse
pix.payout.confirmed	settled	PIX sent and confirmed by the destination. Definitive debit.	Yes
pix.payout.failed	rejected	PIX send rejected by the destination. Hold released, balance restored.	No
pix.payout.returned	returned	Sent PIX was returned after settlement.	Yes (reversal)
pix.refund.requested	requested	PIX refund requested (MED). Preventive block created.	Partial
pix.refund.completed	settled / completed	PIX refund completed and settled. Definitive debit.	Yes
pix.return.received	settled	PIX return received and settled (credit into the account).	Yes
pix.infraction.created	ACKNOWLEDGED	PIX infraction reported against you. Requires action.	Partial - disputed amount may be reserved
pix.infraction.resolved	CLOSED / CANCELLED	Infraction resolved (refund executed or denied).	N/A - effect on another event
pix.infraction.defense_submitted	defense_submitted	Defense submitted by the merchant. Awaiting BACEN.	N/A
webhook.test	test	Test event dispatched manually via Admin/Merchant portal.	N/A

Reconciliation rules:

• Consider balance inflows only on the statuses: paid (PIX IN credit) and returned (reversal of a previously sent PIX OUT).
• Consider balance outflows only on the statuses: settled (confirmed PIX OUT debit) and completed (final MED refund debit), and settled on pix.return.received (reversal of a previously received PIX IN).
• All other statuses (created, queued, processing, rejected, expired, requested, ACKNOWLEDGED, defense_submitted, etc.) are intermediate - they do not trigger accounting movement on your side.
• Do not treat pix.payout.processing as confirmation; wait for the terminal event (pix.payout.confirmed or pix.payout.failed).

---

Common fields

All webhook payloads include these fields:

Field	Type	Description
event_type	string	Type of event that triggered the webhook (e.g., pix.charge.paid)
status	string	Operation status - see Status Reference
account_id	integer	Your account number at Minha Konta
entity_id	string (UUID)	Minha Konta entity identifier

Monetary values: All values are in subcentavos (1 BRL = 10,000 subcentavos). To convert to BRL: value / 10000. Example: 300000 / 10000 = R$ 30.00.

---

pix.charge.paid

Sent when a PIX is received and settled in the account. This is the event that confirms the money came in.

Example - linked to QR code

{
  "event_type": "pix.charge.paid",
  "status": "paid",
  "account_id": 10014,
  "amount": 300000,
  "fee_amount": 400,
  "end_to_end_id": "E9040088820260402095758709999671",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": "u5f26sfyrq4plkw7tjwa",
  "qr_code_id": "f401d5e3-a2b1-4c8e-9f3d-1234567890ab",
  "counterparty_name": "MARIA SANTOS",
  "payer_document": "12345678901",
  "payer_ispb": "60701190",
  "payer_bank_name": "Itau Unibanco S.A.",
  "external_id": "order-9876",
  "paid_at": "2026-04-02T09:58:05Z",
  "recipient_key": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "recipient_key_type": "evp",
  "receiver": {
    "name": "PENHOTA GESTAO E INTERMEDIACAO LTDA",
    "document": "62188010000150",
    "account": "0000000019",
    "ispb": "04838403",
    "institution_name": "AVIVPAY IP"
  }
}

Example - direct transfer (no QR)

{
  "event_type": "pix.charge.paid",
  "status": "paid",
  "account_id": 10014,
  "amount": 300000,
  "fee_amount": 400,
  "end_to_end_id": "E9040088820260402095758709999671",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": null,
  "qr_code_id": null,
  "counterparty_name": "JOAO SILVA",
  "payer_document": "98765432100",
  "payer_ispb": "00000000",
  "payer_bank_name": "Banco do Brasil S.A.",
  "external_id": null,
  "paid_at": "2026-04-02T10:15:22Z",
  "recipient_key": "12345678901",
  "recipient_key_type": "cpf",
  "receiver": {
    "name": "PENHOTA GESTAO E INTERMEDIACAO LTDA",
    "document": "62188010000150",
    "account": "0000000019",
    "ispb": "04838403",
    "institution_name": "AVIVPAY IP"
  }
}

Field	Type	Description
event_type	string	Always pix.charge.paid
status	string	Always paid
account_id	integer	Account number that received the PIX
amount	integer	Amount received in subcentavos. 300000 = R$ 30.00
fee_amount	integer	Fee charged in subcentavos. 400 = R$ 0.04
end_to_end_id	string	BACEN E2E identifier (unique per PIX transaction)
entity_id	string (UUID)	Minha Konta entity identifier
tx_id	string or null	Transaction ID. Present when linked to a QR code. null for direct transfers
qr_code_id	string or null	UUID of the linked QR code. null for direct transfers
counterparty_name	string or null	Name of the payer (sender)
payer_document	string or null	Payer's CPF/CNPJ (digits only)
payer_ispb	string or null	ISPB (8 digits) of the payer's institution
payer_bank_name	string or null	Payer's institution name, resolved via BCB cache (896 banks)
external_id	string or null	Your external identifier. Present when the QR code was created via API with external_id. null for direct transfers or QR without external_id
paid_at	string (ISO 8601)	Settlement date/time (UTC)
recipient_key	string or null	PIX key that received the payment (EVP, CPF, CNPJ, email, or phone)
recipient_key_type	string or null	Recipient PIX key type: evp, phone, email, cpf, cnpj
receiver	object	Full recipient data (you). Includes name, document, account, ispb, institution_name

Payload variation: operational reconciliation

In rare operational reconciliation or incident replay scenarios, pix.charge.paid may be delivered with reduced fields - typically without receiver, payer_ispb, payer_bank_name, recipient_key or recipient_key_type. Fields that are always present: event_type, status, account_id, amount, end_to_end_id, fee_amount, counterparty_name, payer_document, external_id, paid_at, tx_id (when linked to a QR).

Your consumer should treat all non-mandatory fields as optional (nil/absent) and reconcile by end_to_end_id.

qr_code_id is a canonical UUID v4

The qr_code_id field is always serialized as UUID v4 in canonical form (36 characters with hyphens: f401d5e3-a2b1-4c8e-9f3d-1234567890ab) - never as raw binary, base64 or hex without hyphens. Use for direct correlation with the POST /api/external/pix/cash-in response (the transaction_id in your request returns the QR tx_id, and qr_code_id here is the internal primary key).

---

pix.charge.expired

Dispatched automatically when a QR code expires without payment. Expiration checks run periodically and may register the event a few minutes after the actual expires_at.

{
  "event_type": "pix.charge.expired",
  "status": "expired",
  "account_id": 10014,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": "abc123def456ghi789",
  "amount": 500000,
  "external_id": "order-9876",
  "expired_at": "2026-04-02T14:30:00Z"
}

Field	Type	Description
event_type	string	Always pix.charge.expired
status	string	Always expired
account_id	integer	Account that issued the QR code
entity_id	string (UUID)	Minha Konta entity identifier
tx_id	string	Charge/QR code ID
amount	integer	Expected amount in subcentavos (not charged)
external_id	string or null	Your external identifier, if provided at creation
expired_at	string (ISO 8601)	Moment when the API registered expiration (UTC) - may be later than the QR's actual expires_at by a few minutes

---

pix.charge.cancelled

Sent when a QR code is explicitly cancelled by the merchant before it is paid, via action on the portal. Not dispatched on automatic expiration (use pix.charge.expired) or on payment (pix.charge.paid).

{
  "event_type": "pix.charge.cancelled",
  "status": "cancelled",
  "tx_id": "abc123def456ghi789",
  "amount": 500000,
  "account_id": 10014,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "external_id": "order-9876",
  "cancelled_at": "2026-04-23T12:30:00Z"
}

Field	Type	Description
tx_id	string	Charge/QR code ID
amount	integer	Expected amount in subcentavos (not charged)
external_id	string or null	Your external identifier, if provided at creation
cancelled_at	string (ISO 8601)	Moment when cancellation took effect (UTC)

Distinction between cancelled, expired, and paid

• pix.charge.cancelled: merchant intentionally cancelled before payment
• pix.charge.expired: QR lifetime expired
• pix.charge.paid: charge settled successfully

---

pix.charge.created

Sent when a QR code is generated or a cash-in is initiated. No financial movement occurred.

{
  "event_type": "pix.charge.created",
  "status": "created",
  "account_id": 10014,
  "amount": 500000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "tx_id": "abc123def456ghi789",
  "external_id": "order-9876"
}

Field	Type	Description
event_type	string	Always pix.charge.created
status	string	Always created
amount	integer	Expected amount in subcentavos
tx_id	string	Charge/QR code ID
external_id	string or null	Your external identifier, returned as sent. null if not provided or QR generated via portal

---

pix.payout.held

Sent when an outbound PIX is held for review at the settlement agent (authorization/anti-fraud queue, SPI status AGUARDANDO_AUTORIZACAO). The operation has NOT failed: it settles (pix.payout.confirmed) or is rejected (pix.payout.failed) once the agent decides — typically within minutes. Do not resubmit the payment: the amount remains reserved and a resubmission would create a duplicate payment. Emitted at most once per operation, after ~2 minutes without confirmation.

{
  "event_type": "pix.payout.held",
  "status": "processing",
  "account_id": 10014,
  "amount": 500000,
  "end_to_end_id": "E0483840320260402101500000001",
  "transaction_id": "PIXOUT1027803798e62a0f502761008061",
  "external_id": "payment-456",
  "reason": "held_at_settlement_agent",
  "spi_status": "AGUARDANDO_AUTORIZACAO",
  "held_since": "2026-06-10T16:45:36Z"
}

Field	Type	Description
event_type	string	Always pix.payout.held
status	string	Always processing — non-terminal state
reason	string	Always held_at_settlement_agent
spi_status	string	SPI status queried at emission time (e.g. AGUARDANDO_AUTORIZACAO)
held_since	string (ISO 8601)	When the PACS.008 was sent (hold start)
amount	integer	Amount in subcents
external_id	string or null	Your external identifier

---

pix.payout.confirmed

Sent when a sent PIX is confirmed by the destination institution. Definitive debit.

{
  "event_type": "pix.payout.confirmed",
  "status": "settled",
  "account_id": 10014,
  "amount": 500000,
  "fee_amount": 200,
  "end_to_end_id": "E0483840320260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "payment-456",
  "pix_key": "destinatario@email.com",
  "pix_key_type": "EMAIL",
  "description": "Pagamento fornecedor",
  "initiated_at": "2026-04-02T10:14:59Z",
  "recipient": {
    "name": "EMPRESA DESTINO LTDA",
    "document": "12345678000199",
    "ispb": "60701190",
    "account": "12345678",
    "agency": "0001",
    "institution_name": "Itau Unibanco S.A."
  },
  "sender": {
    "name": "MINHA EMPRESA LTDA",
    "document": "98765432000100",
    "ispb": "04838403",
    "account": "00001234",
    "agency": "0001"
  }
}

Field	Type	Description
event_type	string	Always pix.payout.confirmed
status	string	Always settled - definitive debit
amount	integer	Sent amount in subcentavos
fee_amount	integer	Fee charged in subcentavos
end_to_end_id	string	BACEN E2E identifier
transaction_id	string (UUID)	Unique transaction identifier
external_id	string or null	Your external identifier
pix_key	string	Recipient's PIX key
pix_key_type	string	Key type: CPF, CNPJ, EMAIL, PHONE, EVP
description	string or null	Description provided by the sender
initiated_at	string (ISO 8601)	Moment when this webhook was dispatched (UTC). Not the timestamp of the original cash-out request nor of the BACEN settlement. To correlate with the moment you sent the POST, use the created_at from GET /api/external/transactions/ref/{external_id}; for the exact webhook delivery moment, use the X-Minha Konta-Timestamp header
recipient	object	Recipient's bank data (resolved via DICT)
recipient.name	string or null	Destination account holder name
recipient.document	string or null	Recipient's CPF/CNPJ (digits only)
recipient.ispb	string or null	Destination institution ISPB
recipient.account	string or null	Destination account number
recipient.agency	string or null	Destination account agency
recipient.institution_name	string or null	Destination institution name (resolved via BCB cache)
sender	object	Sender account bank data (your Minha Konta account)
sender.name	string or null	Sender account holder name
sender.document	string or null	Sender's CPF/CNPJ (digits only)
sender.ispb	string or null	Minha Konta's ISPB (04838403)
sender.account	string or null	Sender account number
sender.agency	string or null	Sender account agency

---

pix.payout.processing

Sent when a PIX send is being processed. Balance is on hold but not definitive. This event is optional - if you only want to be notified in the terminal state, ignore it and wait for pix.payout.confirmed or pix.payout.failed.

{
  "event_type": "pix.payout.processing",
  "status": "processing",
  "account_id": 10014,
  "amount": 500000,
  "fee_amount": 200,
  "end_to_end_id": "E0483840320260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "payment-456",
  "pix_key": "destinatario@email.com",
  "pix_key_type": "EMAIL",
  "description": "Pagamento fornecedor",
  "initiated_at": "2026-04-02T10:14:59Z",
  "recipient": {
    "name": "EMPRESA DESTINO LTDA",
    "document": "12345678000199",
    "ispb": "60701190",
    "account": "12345678",
    "agency": "0001",
    "institution_name": "Itau Unibanco S.A."
  },
  "sender": {
    "name": "MINHA EMPRESA LTDA",
    "document": "98765432000100",
    "ispb": "04838403",
    "account": "00001234",
    "agency": "0001"
  }
}

Field	Type	Description
event_type	string	Always pix.payout.processing
status	string	Always processing - balance on hold, may reverse
amount	integer	Value in subcentavos
fee_amount	integer	Fee in subcentavos (same fee that will appear in confirmed/failed later - it is computed at cash-out creation, not afterward)
end_to_end_id	string	BACEN E2E identifier
transaction_id	string (UUID)	Unique transaction identifier
external_id	string or null	Your external identifier
pix_key	string	Recipient's PIX key
pix_key_type	string	Key type: CPF, CNPJ, EMAIL, PHONE, EVP
description	string or null	Description provided by the sender
initiated_at	string (ISO 8601)	Moment this webhook was dispatched (UTC) - see note in pix.payout.confirmed
recipient	object	Recipient's bank data (resolved via DICT)
recipient.name	string or null	Destination account holder name
recipient.document	string or null	Recipient's CPF/CNPJ (digits only)
recipient.ispb	string or null	Destination institution ISPB
recipient.account	string or null	Destination account number
recipient.agency	string or null	Destination account agency
recipient.institution_name	string or null	Destination institution name
sender	object	Sender account bank data (your Minha Konta account)
sender.name	string or null	Sender account holder name
sender.document	string or null	Sender's CPF/CNPJ (digits only)
sender.ispb	string or null	Minha Konta's ISPB (04838403)
sender.account	string or null	Sender account number
sender.agency	string or null	Sender account agency

Event order

A pix.payout.processing is always followed (seconds to minutes later) by a pix.payout.confirmed or pix.payout.failed. In fast transactions (immediate settlement), processing may be omitted and you receive the terminal directly.

---

pix.payout.failed

Sent when a sent PIX is rejected. Hold released, balance restored.

Updated on 2026-04-10

The payload includes the structured fields reason_code (BACEN SPI code of 2-6 characters) and reason_description (English description). New integrations should use these fields for programmatic failure routing.

Mutual exclusion: when the API identifies a BACEN code in the rejection (e.g., "rejected: AC03"), the payload sends only reason_code + reason_description - the legacy reason field is removed. When the failure has no parseable BACEN code (e.g., internal timeout, provider error without a code), the payload sends only reason (free string) - no reason_code. Handle both formats in your consumer.

{
  "event_type": "pix.payout.failed",
  "status": "rejected",
  "account_id": 10014,
  "amount": 500000,
  "fee_amount": 200,
  "end_to_end_id": "E0483840320260402101500000001",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "payment-456",
  "pix_key": "destinatario@email.com",
  "pix_key_type": "EMAIL",
  "description": "Pagamento fornecedor",
  "initiated_at": "2026-04-02T10:14:59Z",
  "reason_code": "AC03",
  "reason_description": "Invalid creditor account number",
  "reason": "Conta destinatario nao encontrada",
  "recipient": {
    "name": "EMPRESA DESTINO LTDA",
    "document": "12345678000199",
    "ispb": "60701190",
    "account": "12345678",
    "agency": "0001",
    "institution_name": "Itau Unibanco S.A."
  },
  "sender": {
    "name": "MINHA EMPRESA LTDA",
    "document": "98765432000100",
    "ispb": "04838403",
    "account": "00001234",
    "agency": "0001"
  }
}

Field	Type	Description
event_type	string	Always pix.payout.failed
status	string	Always rejected - hold released, balance restored
amount	integer	Value in subcentavos
fee_amount	integer	Fee in subcentavos. The fee shown is what would have been charged - on the TB ledger the pending transfer is automatically reverted, so in practice there is no fee debit on rejected transactions
end_to_end_id	string	BACEN E2E identifier
transaction_id	string (UUID)	Unique transaction identifier
external_id	string or null	Your external identifier
pix_key	string	Recipient's PIX key
pix_key_type	string	Key type: CPF, CNPJ, EMAIL, PHONE, EVP
description	string or null	Description provided by the sender
initiated_at	string (ISO 8601)	Moment this webhook was dispatched (UTC)
reason_code	string or absent	Structured BACEN SPI code (2-6 characters). Examples: AC03, ED05, AM02, BE01, MD06, FOCR. Present when the API identified a BACEN code in the rejection. Use this field for programmatic routing
reason_description	string or absent	English description of the reason_code. Present along with reason_code. Example: "Invalid creditor account number"
reason	string or absent	[Legacy] Free-form description of the reason. Present only when the rejection has no parseable BACEN code - mutually exclusive with reason_code
recipient	object	Recipient's bank data (resolved via DICT)
recipient.name	string or null	Destination account holder name
recipient.document	string or null	Recipient's CPF/CNPJ (digits only)
recipient.ispb	string or null	Destination institution ISPB
recipient.account	string or null	Destination account number
recipient.agency	string or null	Destination account agency
recipient.institution_name	string or null	Destination institution name
sender	object	Sender account bank data (your Minha Konta account)
sender.name	string or null	Sender account holder name
sender.document	string or null	Sender's CPF/CNPJ (digits only)
sender.ispb	string or null	Minha Konta's ISPB (04838403)
sender.account	string or null	Sender account number
sender.agency	string or null	Sender account agency

Payload variations across dispatch sites

pix.payout.failed may be emitted by more than one operational flow. In some scenarios, the payload may send both reason and reason_code, or only reason without structure. Always treat both fields as optional and prefer reason_code when present.

Most common reason_code (BACEN SPI)

Code	English meaning	Recommended action
AC03	Invalid creditor account number	Confirm recipient's bank data with the end customer
AC06	Creditor account blocked	Destination account blocked - do not retry
AM02	Not allowed amount (limit exceeded)	Amount exceeds destination's or source's PIX limit
AM04	Insufficient funds	Insufficient funds at the source
BE01	End customer not in whitelist	Recipient identifier not recognized
ED05	Settlement failed	Settlement failure - may retry after investigation
MD06	Refund requested by end customer	Refund requested by the end customer
FOCR	Forbidden credit return	Credit return forbidden

Full list: see the SPI Message Catalog by BACEN.

---

pix.payout.returned

Sent when a PIX you sent is returned by the destination bank after settlement. Rare, but can happen several days later. The merchant balance increases (inflow).

Naming distinction

Three different flows can be confused:

• pix.return.received: a PIX you received is being returned to the original payer. Balance DECREASES.
• pix.payout.returned (this): a PIX you sent is coming back to you. Balance INCREASES.
• pix.refund.requested: MED preventive block on a PIX you received. Funds frozen.

Same payload, two events, two different statuses

The API may dispatch pix.return.received and pix.payout.returned for the same refund using the same base payload with the status field adjusted for each event:

• pix.return.received → status: "settled" (PIX you received is being returned → balance decreases)
• pix.payout.returned → status: "returned" (PIX you sent is coming back → balance increases)

If your reconciliation logic filters by status or dedupes by (e2e, event_type), make sure to distinguish event_type first - the payload is almost identical.

{
  "event_type": "pix.payout.returned",
  "status": "returned",
  "account_id": 10014,
  "amount": 500000,
  "original_amount": 500000,
  "refunded_amount": 500000,
  "fee_amount": 0,
  "net_amount": 500000,
  "is_partial": false,
  "total_refunded": 500000,
  "remaining_refundable": 0,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "return_e2e_id": "D0483840320260410111500000001",
  "end_to_end_id": "E0483840320260402101500000001",
  "original_transaction_id": "PIXOUTa1b2c3d4e5f67890abcdef1234567890",
  "external_id": "payment-456",
  "return_reason": "MD06",
  "return_reason_description": "Refund requested by end customer",
  "counterparty_ispb": "60701190",
  "counterparty_name": "EMPRESA DESTINO LTDA",
  "counterparty_document": "12345678000199",
  "counterparty_institution_name": "Itau Unibanco S.A.",
  "returned_at": "2026-04-10T11:15:00Z"
}

Field	Type	Description
event_type	string	Always pix.payout.returned
status	string	Always returned - return settled and credited to your account
amount	integer	Same value as refunded_amount (kept for compatibility)
original_amount	integer	Value of the original PIX OUT in subcentavos
refunded_amount	integer	Amount effectively returned in this return (may be partial)
fee_amount	integer	Fee charged on this return (usually 0)
net_amount	integer	refunded_amount - fee_amount
is_partial	boolean	true when refunded_amount < original_amount or balance remains to be returned
total_refunded	integer	Sum of all returns already received for this original transaction (includes this one)
remaining_refundable	integer	max(original_amount - total_refunded, 0) - balance still refundable
return_e2e_id	string	Return E2E (prefix D)
end_to_end_id	string	E2E of the original PIX OUT (prefix E)
original_transaction_id	string	transaction_id of the original PIX OUT. Use for correlation with your system
external_id	string or null	Your external identifier from the original transaction (if applicable)
return_reason	string	BACEN return code: MD06, BE08, FR01, SL02
return_reason_description	string	English description of return_reason
counterparty_ispb	string	ISPB of the institution that initiated the return
counterparty_name	string	Counterparty name (destination institution of the original PIX)
counterparty_document	string or null	Counterparty's CPF/CNPJ
counterparty_institution_name	string or null	Counterparty institution name (BCB cache)
returned_at	string (ISO 8601)	Moment this webhook was dispatched (UTC)

Fee is not reimbursed

The fee of the original cash-out is not reimbursed on pix.payout.returned. The fee was charged for the successful send that actually happened. If your business rule requires reimbursing the fee to the end customer, the merchant must do this separately.

---

pix.refund.requested

Sent when a PIX refund is requested via MED (Special Refund Mechanism). Funds were preventively blocked in the account of the merchant that received the original PIX.

PIX In only

This event applies only to received PIX (cash-in). If you sent a PIX and it was returned, you will receive pix.return.received instead of pix.refund.*.

{
  "event_type": "pix.refund.requested",
  "status": "requested",
  "account_id": 10014,
  "requested_amount": 300000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "block_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
  "infraction_report_id": "INF20260402001",
  "e2e_id": "E9040088820260402095758709999671",
  "external_id": null,
  "blocked_amount": 300000,
  "fee_amount": 0,
  "fraud_category": "OTHER",
  "deadline": "2026-04-09T14:30:00Z",
  "scenario": "cautelar",
  "created_at": "2026-04-02T14:30:00Z"
}

Field	Type	Description
event_type	string	Always pix.refund.requested
status	string	Always requested - preventive block active
requested_amount	integer	Amount requested for refund in subcentavos
block_id	string (UUID)	Preventive block identifier
infraction_report_id	string	Infraction identifier at the PIX provider
e2e_id	string	E2E of the original PIX transaction being disputed
external_id	string or null	Your external identifier (if applicable)
blocked_amount	integer	Amount effectively blocked in subcentavos
fee_amount	integer	MED fee in subcentavos
fraud_category	string	Category of alleged fraud. Possible values: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER. When the counterparty does not send a specific FraudType, the value is OTHER (default for REFUND_REQUEST).
deadline	string (ISO 8601)	Deadline for analysis/defense (UTC)
scenario	string	MED scenario: cautelar or fraude
created_at	string (ISO 8601)	Block date/time (UTC)

---

pix.refund.completed

Dispatched when a MED refund is successfully executed. Dispatched via med/processor.ex:915 during the accepted MED cycle.

Payload format (confirmed by code path med/processor.ex:900-920):

{
  "event_type": "pix.refund.completed",
  "status": "settled",
  "account_id": 10014,
  "amount": 300000,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "block_id": "b1c2d3e4-f5g6-7890-hijk-lm1234567890",
  "infraction_report_id": "INF20260402001",
  "e2e_id": "E9040088820260402095758709999671",
  "external_id": null,
  "reason": "analysis_unfounded",
  "completed_at": "2026-04-02T14:30:00Z"
}

Field	Type	Description
event_type	string	Always pix.refund.completed
status	string	Always completed - MED refund finalized
amount	integer	Amount refunded in subcentavos
block_id	string (UUID)	Preventive block identifier
infraction_report_id	string	PIX provider infraction identifier
e2e_id	string	E2E of the original PIX transaction
external_id	string or null	Your external identifier (if applicable)
reason	string	Release reason (e.g., analysis_unfounded, manual_release)
completed_at	string (ISO 8601)	Completion date/time (UTC)

---

pix.return.received

Sent when a PIX return is received. This event is generated when a PIX that you previously received (cash-in) is being returned to the original payer. The merchant balance decreases.

Naming distinction

• pix.return.received (this): a PIX you received is being returned to the original payer. Balance DECREASES.
• pix.payout.returned: a PIX you sent is coming back to you. Balance INCREASES.

The names are inverse to what the plain meaning suggests - pay attention.

{
  "event_type": "pix.return.received",
  "status": "settled",
  "account_id": 10014,
  "amount": 300000,
  "original_amount": 300000,
  "refunded_amount": 300000,
  "fee_amount": 0,
  "net_amount": 300000,
  "is_partial": false,
  "total_refunded": 300000,
  "remaining_refundable": 0,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "return_e2e_id": "D9040088820260402111500000001",
  "end_to_end_id": "E9040088820260402095758709999671",
  "original_transaction_id": "PIXINE9040088820260402095758709999671",
  "external_id": null,
  "return_reason": "MD06",
  "return_reason_description": "Refund requested by end customer",
  "counterparty_ispb": "60701190",
  "counterparty_name": "EMPRESA X LTDA",
  "counterparty_document": "98765432100",
  "counterparty_institution_name": "Itau Unibanco S.A.",
  "returned_at": "2026-04-02T11:15:00Z"
}

Field	Type	Description
event_type	string	Always pix.return.received
status	string	Always settled - return settled
amount	integer	Same value as refunded_amount (kept for compatibility)
original_amount	integer	Value of the original PIX IN in subcentavos
refunded_amount	integer	Amount effectively returned in this return (may be partial)
fee_amount	integer	Fee charged on this return
net_amount	integer	refunded_amount - fee_amount
is_partial	boolean	true when the return does not cover the original PIX IN's full amount
total_refunded	integer	Sum of all returns already sent for this transaction (includes this one)
remaining_refundable	integer	Balance still refundable
return_e2e_id	string	Return E2E (prefix D)
end_to_end_id	string	E2E of the original PIX IN (prefix E)
original_transaction_id	string	transaction_id of the original PIX IN. Use for correlation with your system
external_id	string or null	Your external identifier from the original transaction (if applicable)
return_reason	string	BACEN return code: MD06, BE08, FR01, SL02
return_reason_description	string	English description of return_reason
counterparty_ispb	string	ISPB of the institution receiving the return
counterparty_name	string	Counterparty name (original PIX IN payer)
counterparty_document	string or null	Counterparty's CPF/CNPJ
counterparty_institution_name	string or null	Counterparty institution name (BCB cache)
returned_at	string (ISO 8601)	Moment this webhook was dispatched (UTC)

Deduplication

To deduplicate webhook retries, use the X-Minha Konta-Event-Id header OR the combination (return_e2e_id, end_to_end_id). The return_e2e_id starts with D (return) and the end_to_end_id starts with E (original).

---

webhook.test

Test event dispatched manually to validate webhook configuration.

{
  "event_type": "webhook.test",
  "status": "test",
  "account_id": 10014,
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7",
  "message": "Webhook test event"
}

---

pix.infraction.created

Dispatched when a PIX infraction is reported by the counterparty (via BACEN DICT). Use defense_deadline to track the response deadline.

{
  "event_type": "pix.infraction.created",
  "infraction_id": "e7f4d23a-6f2a-4d1e-a3e6-fe8b32bba95d",
  "e2e_id": "E0416201020260404113012abcdef1234",
  "status": "ACKNOWLEDGED",
  "infraction_type": "REFUND_REQUEST",
  "amount": 1500000,
  "analysis_result": null,
  "analysis_details": null,
  "defense_deadline": "2026-04-21T23:59:59Z",
  "counterpart_ispb": "60701190",
  "account_id": 10011,
  "merchant_id": "1b2db911-972f-4466-9be9-60a7c5450064",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}

Field	Type	Description
event_type	string	Always pix.infraction.created
infraction_id	string (UUID)	Internal infraction ID
e2e_id	string	E2E of the disputed transaction
status	string	BACEN status: ACKNOWLEDGED, CLOSED, CANCELLED
infraction_type	string	BACEN type: REFUND_REQUEST, REFUND_CANCELLED, FRAUD
amount	integer	Value in subcentavos
defense_deadline	string (ISO 8601)	Deadline for defense submission
counterpart_ispb	string (8 digits)	Counterparty institution ISPB
account_id	integer	Your affected account
merchant_id	string (UUID)	Your merchant_id

Action needed

Infractions with status ACKNOWLEDGED may require MED analysis. Respond through the portal or External API (POST /api/external/med/:id/defense) before defense_deadline when you have defense and evidence.

---

pix.infraction.resolved

Dispatched when an infraction is resolved. It reports the final result and releases the applicable financial flow.

{
  "event_type": "pix.infraction.resolved",
  "infraction_id": "e7f4d23a-6f2a-4d1e-a3e6-fe8b32bba95d",
  "e2e_id": "E0416201020260404113012abcdef1234",
  "status": "CLOSED",
  "infraction_type": "REFUND_REQUEST",
  "amount": 1500000,
  "analysis_result": "DISAGREED",
  "analysis_details": "Verificado pelo time de compliance e sem evidencias concretas nao temos como fazer devolucao",
  "defense_deadline": "2026-04-21T23:59:59Z",
  "counterpart_ispb": "60701190",
  "account_id": 10011,
  "merchant_id": "1b2db911-972f-4466-9be9-60a7c5450064",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}

Field	Type	Description
analysis_result	string	AGREED (refund), DISAGREED (deny)
analysis_details	string	Decision justification
Other fields		Identical to pix.infraction.created

---

pix.infraction.defense_submitted

Dispatched when a defense is registered against an infraction/MED through Minha Konta portals or the External API.

{
  "event_type": "pix.infraction.defense_submitted",
  "infraction_id": "e7f4d23a-6f2a-4d1e-a3e6-fe8b32bba95d",
  "e2e_id": "E0416201020260404113012abcdef1234",
  "status": "defense_submitted",
  "account_id": 10011,
  "merchant_id": "1b2db911-972f-4466-9be9-60a7c5450064",
  "entity_id": "26a48541-edce-4581-8c6e-564e7f2e6cd7"
}

Field	Type	Description
event_type	string	Always pix.infraction.defense_submitted
status	string	Always defense_submitted
infraction_id	string (UUID)	ID of the infraction being defended

Stored evidence

Defense attachments remain stored at Minha Konta for analysis and audit. The final result arrives through pix.infraction.resolved.

---

pix.payout.queued

Dispatched when a PIX OUT is automatically placed in the retry queue. Common reasons: operational limit per merchant or temporary unavailability of BACEN DICT capacity.

{
  "event_type": "pix.payout.queued",
  "status": "queued",
  "account_id": 10011,
  "merchant_id": "1b2db911-972f-4466-9be9-60a7c5450064",
  "transaction_id": "PIXOUT0200806193e0984f830569",
  "end_to_end_id": "E0483840320260421133012abcdef1234",
  "amount": 200,
  "external_id": "payment-456",
  "reason": "dict_client_rate_limited",
  "reason_code": "DICT_CLIENT_RATE_LIMITED",
  "reason_description": "Merchant exceeded per-minute DICT lookup quota",
  "queued_at": "2026-04-21T13:30:12Z",
  "estimated_retry_seconds": 3,
  "queue_ttl_seconds": 7200
}

Field	Type	Description
event_type	string	Always pix.payout.queued
status	string	Always queued
account_id	integer	Account that originated the PIX OUT
merchant_id	string (UUID)	Your merchant_id
transaction_id	string	Minha Konta transaction identifier
end_to_end_id	string	BACEN E2E generated for the PIX OUT
amount	integer	Value in subcentavos
external_id	string or null	Your external identifier (if sent in the original request)
reason	string	Queue reason (snake_case). Known values: dict_client_rate_limited (per-merchant limit), dict_bucket_exhausted (shared BACEN DICT bucket exhausted), dict_rate_limited (generic fallback)
reason_code	string	Internal UPPERCASE code correlated with reason. Values: DICT_CLIENT_RATE_LIMITED, DICT_BUCKET_EXHAUSTED, DICT_RATE_LIMITED. Not a BACEN SPI code (like AC03, AM02) - the queueing happens before sending to BACEN, so the codes are internal to Minha Konta
reason_description	string	English description of the reason
queued_at	string (ISO 8601)	Moment it entered the queue (UTC)
estimated_retry_seconds	integer	Estimated retry interval; the queue does not guarantee this timing and may take longer if external capacity takes time to recover
queue_ttl_seconds	integer	Maximum TTL in the queue in seconds (7200 = 2 h). After expiration, the request goes to failed with reason queue_ttl_expired

reason_code here is not BACEN SPI

Note that in pix.payout.queued the reason_code is an Minha Konta internal UPPERCASE code (DICT_CLIENT_RATE_LIMITED, etc.). In pix.payout.failed the reason_code is a BACEN SPI code (e.g., AC03, AM02, ED05). The two fields share the same name but have different vocabularies - handle each event separately in your consumer.

Automatic drain

Queued requests are retried automatically while TTL remains. Under normal conditions processing resumes as soon as the per-merchant limit or BACEN DICT bucket has capacity, but this is not a 3-10 min SLA. Next event: pix.payout.processing (when it leaves the queue and is sent to BACEN). If the 2-hour TTL expires without success, you receive pix.payout.failed with reason="queue_ttl_expired".

---

How to interpret webhooks

To confirm money came into the account: Wait for pix.charge.paid with status: "paid". This is the only event that guarantees the value was credited and the fee was charged.

To confirm money left the account: Wait for pix.payout.confirmed with status: "settled". The processing status is intermediate - the balance is reserved but can be reverted if rejected.

For returns: pix.return.received with status: "settled" confirms that a return was settled and credited to the account.

Deduplication: Use the X-Minha Konta-Event-Id header or the end_to_end_id field as an idempotency key.