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. Seu gerente de contas registra o endpoint HTTPS que os recebe; as entregas são enviadas via HTTPS para essa URL previamente registrada.

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

Pagamentos e cobranças

Evento	Dispara quando	Guia
`PIX_BILLING_PAID`	Uma cobrança PIX (QR Code) é paga.	Cobrar com PIX
`PIX_BILLING_AUTOMATIC_CREATED` · `INITIATED` · `SCHEDULED` · `EXPIRED` · `CANCELED`	A autorização recorrente muda de estado.	PIX Automático
`PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` · `SCHEDULED` · `PAID` · `FAILED` · `CANCELED`	Um ciclo recorrente individual muda de estado.	PIX Automático
`BOLETO_BILLING_UPDATED`	Uma cobrança por boleto muda de estado (por exemplo, para `CREATED` com o código de barras).	PIX Automático

Cartões e carteiras

Evento	Dispara quando	Guia
`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`	Um cartão é debitado, ou uma cobrança é recusada.	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

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

Pagamentos e cobranças

Cartões e carteiras

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

​Pagamentos e cobranças

​Cartões e carteiras

​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

Pagamentos e cobranças

Cartões e carteiras

Exemplo: provisionamento guiado por webhooks

Consultar uma organização

Próximos passos