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. Your account manager registers the HTTPS endpoint that receives them; deliveries are sent over HTTPS to that pre-registered 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

Payments and charges

Event	Fires when	Guide
`PIX_BILLING_PAID`	A PIX charge (QR Code) is paid.	Charge with PIX
`PIX_BILLING_AUTOMATIC_CREATED` · `INITIATED` · `SCHEDULED` · `EXPIRED` · `CANCELED`	The recurring authorization changes state.	Pix Automático
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` · `SCHEDULED` · `PAID` · `FAILED` · `CANCELED`	An individual recurring cycle changes state.	Pix Automático
`BOLETO_BILLING_UPDATED`	A boleto charge changes state (for example, to `CREATED` with its barcode).	Pix Automático

Cards and wallets

Event	Fires when	Guide
`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`	A card is charged, or a charge is refused.	Manage cards
`CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT`	A card needs a device-wallet verification code.	Manage cards

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

Payments and charges

Cards and wallets

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

​Payments and charges

​Cards and wallets

​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

Payments and charges

Cards and wallets

Example: provisioning driven by webhooks

Looking up an organization

Next steps