Receive webhooks

Most flows in these guides finish asynchronously — a PIX is paid, a card is charged, a recurring cycle settles. Portão 3 tells you about these by webhook. You register the HTTPS endpoint that receives them yourself, through the Notification API’s Webhooks section (POST /realms/{realmId}/organizations/{organizationId}/webhooks — one URL subscribed to the events you want; registering the same URL again adds events to it, and each event can be switched off and back on per webhook); deliveries are sent over HTTPS to that URL.

The notification envelope

Every webhook shares the same envelope. The event tells you what happened; the payload is the affected resource.

{
  "notificationId": "03d55ca0-b64d-4484-a8e3-9b38528e4818",
  "source": "WALLET",
  "event": "PIX_BILLING_PAID",
  "payload": {
    "_id": "68823710b8a3dbd2b90ff8d5",
    "status": "PAID"
  }
}

Field	Meaning
`notificationId`	Unique per delivery. Use it to deduplicate — see below.
`source`	The originating domain. Banking events use `WALLET`.
`event`	The event name (see the catalog below).
`payload`	The resource the event is about, in the same shape the API returns it.

Webhooks can be delivered more than once. Treat notificationId as an idempotency key: record the ones you’ve processed and ignore repeats. Always respond 2xx quickly and do your processing asynchronously.

Event catalog

A subscription is a { "source", "event" } pair, and the event must belong to its source — the register endpoint rejects any other combination with a 422. These are the three sources and every event each one accepts, exactly as the API validates them.

`WALLET` — payments, cards and wallets

Event	Fires when	Guide
`PIX_IN`	A PIX is received in a wallet.	—
`PIX_OUT`	A PIX is sent from a wallet.	—
`BANK_SLIP_PAID`	A boleto is paid from a wallet.	—
`FEE`	A fee is debited from a wallet.	—
`PIX_BILLING_PAID`	A PIX charge (QR Code) is paid.	Charge with PIX
`PIX_BILLING_AUTOMATIC_CREATED` · `PIX_BILLING_AUTOMATIC_INITIATED` · `PIX_BILLING_AUTOMATIC_SCHEDULED` · `PIX_BILLING_AUTOMATIC_EXPIRED` · `PIX_BILLING_AUTOMATIC_CANCELED`	The recurring authorization changes state.	Pix Automático
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` · `PIX_BILLING_AUTOMATIC_SCHEDULE_SCHEDULED` · `PIX_BILLING_AUTOMATIC_SCHEDULE_PAID` · `PIX_BILLING_AUTOMATIC_SCHEDULE_FAILED` · `PIX_BILLING_AUTOMATIC_SCHEDULE_CANCELED`	An individual recurring cycle changes state.	Pix Automático
`WALLET_CREATED`	A wallet is created.	This guide
`WALLET_UPDATED`	A wallet changes — including its `customFields`.	This guide
`WALLET_CARD_CREATED`	A card is created on a wallet.	Manage cards
`CARD_TRANSACTION` · `CARD_TRANSACTION_REFUSED` · `CARD_TRANSACTION_REFUNDED`	A card is charged, a charge is refused, or a charge is refunded by the merchant.	Manage cards
`CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT`	A card needs a device-wallet verification code.	Manage cards

`BILLING` — deals and invoices

Event	Fires when
`BILLING_DEAL_CREATED` · `BILLING_DEAL_CANCELED` · `BILLING_DEAL_TERMINATED`	A deal is created, canceled or terminated.
`BILLING_INVOICE_CREATED` · `BILLING_INVOICE_CLOSED` · `BILLING_INVOICE_PAID` · `BILLING_INVOICE_STATUS_UPDATED`	An invoice is created, closed, paid, or changes status.
`BILLING_INVOICE_PAYMENT_CREATED` · `BILLING_INVOICE_PAYMENT_SCHEDULED` · `BILLING_INVOICE_PAYMENT_PAID`	A payment of an invoice is created, scheduled or paid.

`TRAVEL` — bookings

Event	Fires when
`TRAVEL_RESERVATION_CREATED` · `TRAVEL_RESERVATION_ISSUED` · `TRAVEL_RESERVATION_CANCELED` · `TRAVEL_RESERVATION_EXPIRED` · `TRAVEL_RESERVATION_FAILED`	A travel booking is created, issued, canceled, expires, or fails.

A boleto charge (POST .../boleto-billing) has no webhook: read it back with GET .../boleto-billing/{boletoId} to follow its status.

Example: provisioning driven by webhooks

A common pattern is to let users self-onboard in the Portão 3 app and have your system react to webhooks rather than calling the API yourself. For example, when a user is invited and links a card, you receive: Custom fields are carried as customFields on both wallets and transactions — a map keyed by the field definition’s slug ({ "cost-center": "Projetos", "valid": true }). Resolve labels/types by fetching the definitions from the custom-fields API. Use them to attach your own identifiers — a driver’s CPF, a mileage reading, an invoice file.

Only wallet custom-field changes emit a webhook (WALLET_UPDATED). Changes to a transaction’s custom fields do not emit one — read them back from the transaction itself. (The former TRANSACTION_CUSTOM_FIELDS_UPDATED event is no longer sent.)

Webhook payloads and custom fields can carry personal data (names, CPF/CNPJ, emails, addresses). Store only what you need, keep it out of plaintext logs, and follow your own retention and minimization obligations under the LGPD.

Looking up an organization

To resolve an organization’s registration details (legal name, document, address) from its realmId and organizationId — handy when reconciling webhook payloads — use the Identity organization endpoint:

curl 'https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}' \
  -H 'Authorization: Bearer <accessToken>'

Reference: GET /realms/{realmId}/organizations/{organizationId}

Next steps

Charge with PIX

The simplest webhook-driven flow to test against.

Recurring billing with Pix Automático

The flow with the richest event lifecycle.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

The notification envelope

Event catalog

`WALLET` — payments, cards and wallets

`BILLING` — deals and invoices

`TRAVEL` — bookings

Example: provisioning driven by webhooks

Looking up an organization

Next steps

Charge with PIX

Recurring billing with Pix Automático

​The notification envelope

​Event catalog

​WALLET — payments, cards and wallets

​BILLING — deals and invoices

​TRAVEL — bookings

​Example: provisioning driven by webhooks

​Looking up an organization

​Next steps

Charge with PIX

Recurring billing with Pix Automático

The notification envelope

Event catalog

`WALLET` — payments, cards and wallets

`BILLING` — deals and invoices

`TRAVEL` — bookings

Example: provisioning driven by webhooks

Looking up an organization

Next steps