Receber webhooks

A maioria dos fluxos destes guias termina de forma assíncrona — um PIX é pago, um cartão é debitado, um ciclo recorrente é liquidado. O Portão 3 avisa você sobre isso por webhook. Você mesmo registra o endpoint HTTPS que os recebe, pela seção Webhooks da API de Notification (POST /realms/{realmId}/organizations/{organizationId}/webhooks — uma URL inscrita nos eventos que quiser; registrar a mesma URL de novo adiciona eventos a ela, e cada evento pode ser desativado e reativado por webhook); as entregas são enviadas via HTTPS para essa URL.

O envelope de notificação

Todo webhook compartilha o mesmo envelope. O event informa o que aconteceu; o payload é o recurso afetado.

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

Campo	Significado
`notificationId`	Único por entrega. Use-o para deduplicar — veja abaixo.
`source`	O domínio de origem. Eventos de Banking usam `WALLET`.
`event`	O nome do evento (veja o catálogo abaixo).
`payload`	O recurso ao qual o evento se refere, no mesmo formato que a API retorna.

Webhooks podem ser entregues mais de uma vez. Trate notificationId como uma chave de idempotência: registre os que você já processou e ignore repetições. Sempre responda 2xx rapidamente e faça o processamento de forma assíncrona.

Catálogo de eventos

Uma inscrição é um par { "source", "event" }, e o event precisa pertencer ao seu source — o endpoint de registro rejeita qualquer outra combinação com 422. Estes são os três sources e todos os eventos que cada um aceita, exatamente como a API os valida.

`WALLET` — pagamentos, cartões e carteiras

Evento	Dispara quando	Guia
`PIX_IN`	Um PIX é recebido em uma carteira.	—
`PIX_OUT`	Um PIX é enviado de uma carteira.	—
`BANK_SLIP_PAID`	Um boleto é pago a partir de uma carteira.	—
`FEE`	Uma tarifa é debitada de uma carteira.	—
`PIX_BILLING_PAID`	Uma cobrança PIX (QR Code) é paga.	Cobrar com PIX
`PIX_BILLING_AUTOMATIC_CREATED` · `PIX_BILLING_AUTOMATIC_INITIATED` · `PIX_BILLING_AUTOMATIC_SCHEDULED` · `PIX_BILLING_AUTOMATIC_EXPIRED` · `PIX_BILLING_AUTOMATIC_CANCELED`	A autorização recorrente muda de estado.	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`	Um ciclo recorrente individual muda de estado.	PIX Automático
`WALLET_CREATED`	Uma carteira é criada.	Este guia
`WALLET_UPDATED`	Uma carteira muda — incluindo seus `customFields`.	Este guia
`WALLET_CARD_CREATED`	Um cartão é criado em uma carteira.	Gerenciar cartões
`CARD_TRANSACTION` · `CARD_TRANSACTION_REFUSED` · `CARD_TRANSACTION_REFUNDED`	Um cartão é debitado, uma cobrança é recusada, ou uma cobrança é estornada pelo estabelecimento.	Gerenciar cartões
`CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT`	Um cartão precisa de um código de verificação de carteira de dispositivo.	Gerenciar cartões

`BILLING` — deals e faturas

Evento	Dispara quando
`BILLING_DEAL_CREATED` · `BILLING_DEAL_CANCELED` · `BILLING_DEAL_TERMINATED`	Um deal é criado, cancelado ou encerrado.
`BILLING_INVOICE_CREATED` · `BILLING_INVOICE_CLOSED` · `BILLING_INVOICE_PAID` · `BILLING_INVOICE_STATUS_UPDATED`	Uma fatura é criada, fechada, paga ou muda de status.
`BILLING_INVOICE_PAYMENT_CREATED` · `BILLING_INVOICE_PAYMENT_SCHEDULED` · `BILLING_INVOICE_PAYMENT_PAID`	Um pagamento de fatura é criado, agendado ou pago.

`TRAVEL` — reservas

Evento	Dispara quando
`TRAVEL_RESERVATION_CREATED` · `TRAVEL_RESERVATION_ISSUED` · `TRAVEL_RESERVATION_CANCELED` · `TRAVEL_RESERVATION_EXPIRED` · `TRAVEL_RESERVATION_FAILED`	Uma reserva de viagem é criada, emitida, cancelada, expira ou falha.

Uma cobrança por boleto (POST .../boleto-billing) não tem webhook: consulte-a com GET .../boleto-billing/{boletoId} para acompanhar o status.

Exemplo: provisionamento guiado por webhooks

Um padrão comum é deixar os usuários fazerem o próprio onboarding no aplicativo Portão 3 e seu sistema reagir a webhooks em vez de chamar a API diretamente. Por exemplo, quando um usuário é convidado e vincula um cartão, você recebe: Os campos personalizados são enviados como customFields em carteiras e transações — um mapa cuja chave é o slug da definição do campo ({ "centro-de-custo": "Projetos", "valido": true }). Para obter rótulos/tipos, consulte as definições na API de custom fields.

Apenas mudanças de campos personalizados de carteira emitem webhook (WALLET_UPDATED). Mudanças nos campos personalizados de uma transação não emitem webhook — leia-os na própria transação. (O antigo evento TRANSACTION_CUSTOM_FIELDS_UPDATED não é mais enviado.)

Payloads de webhook e campos personalizados podem carregar dados pessoais (nomes, CPF/CNPJ, e-mails, endereços). Armazene apenas o necessário, mantenha-os fora de logs em texto puro e siga suas próprias obrigações de retenção e minimização sob a LGPD.

Consultar uma organização

Para resolver os dados cadastrais de uma organização (razão social, documento, endereço) a partir de seu realmId e organizationId — útil ao reconciliar payloads de webhook — use o endpoint de organização do Identity:

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

Referência: GET /realms/{realmId}/organizations/{organizationId}

Próximos passos

Cobrar com PIX

O fluxo guiado por webhook mais simples para testar.

Cobrança recorrente com PIX Automático

O fluxo com o ciclo de vida de eventos mais rico.

Primeiros passos

Guias de integração

Cartões

PIX e pagamentos

Contas e carteiras

Construindo sua integração

O envelope de notificação

Catálogo de eventos

`WALLET` — pagamentos, cartões e carteiras

`BILLING` — deals e faturas

`TRAVEL` — reservas

Exemplo: provisionamento guiado por webhooks

Consultar uma organização

Próximos passos

Cobrar com PIX

Cobrança recorrente com PIX Automático

​O envelope de notificação

​Catálogo de eventos

​WALLET — pagamentos, cartões e carteiras

​BILLING — deals e faturas

​TRAVEL — reservas

​Exemplo: provisionamento guiado por webhooks

​Consultar uma organização

​Próximos passos

Cobrar com PIX

Cobrança recorrente com PIX Automático

O envelope de notificação

Catálogo de eventos

`WALLET` — pagamentos, cartões e carteiras

`BILLING` — deals e faturas

`TRAVEL` — reservas

Exemplo: provisionamento guiado por webhooks

Consultar uma organização

Próximos passos