Open Finance

Notificações de eventos – Open Finance

Os eventos vinculados ao Open Finance geram notificações relacionadas à autorização de pagamentos via Pix Automático. Essas notificações são enviadas e informam o usuário sobre o sucesso ou falha no agendamento da transação.

Pré-requisitos

Para que o parceiro possa receber e tratar esses eventos corretamente, é necessário:

Ter o recebedor de eventos via webhook previamente configurado.
Conhecer a estrutura padrão dos eventos de notificação listado abaixo.
Estar integrado à solução de Open Finance conforme instruções da documentação do Open Finance.

Informações sobre os eventos

Todos os eventos de notificação seguem o mesmo padrão do Event Notification. Os seguintes campos são comuns à todos os eventos que implementam o EventNotification.

Nome	Tipo	Descrição
`entityId`	`string`	Identificador da entidade emissora do evento. Portanto, dependerá do contexto de sua emissão. Exemplo: eventos de Pix utilizam como identificador o `authenticationCode` do Pix.
`companyKey`	`string`	Chave que identifica o parceiro dentro da Banco liquidante.
`context`	`string`	Contexto em que o evento foi criado. Os possíveis contextos estão listados na documentação.
`name`	`string`	Nome descritivo que identifica a operação realizada. Seguir nomenclatura padrão dos eventos.
`idempotencyKey`	`string`	Valor retornado para evitar eventos duplicados (em formato `UUID`).
`correlationId`	`string`	Identificador que correlaciona todo o fluxo das operações.
`timestamp`	`string`	Data e hora em que o evento ocorreu, no formato ISO 8601 - UTC.
`version`	`string`	Versão do evento.
`metadata`	`object`	Informações adicionais pertinentes ao contexto, representadas através de pares de chave e valor. Tais informações não fazem parte explicitamente da transação e são sujeitas à variação. Exemplo: tempo de solicitação e tempo de resposta da operação.
`data`	`object`	Entidade relacionada ao `ID`, que varia conforme o evento. Exemplo: em um evento de conta, `data` trará dados da estrutura de uma conta.
`licenseUuid`	`string`	Identificador único da licença.
`licenses`	`array of objects`	Lista que contém as informações sobre a licença bancária.
`licenses[].id`	`string (UUID v4)`	Identificador único da licença.
`licenses[].provider`	`string`	Nome do provedor bancário.
`licenses[].types`	`array of strings`	Tipos da licença bancária. No contexto de Open Finance, sempre será `"BANKING"`.

OPENFINANCE_AUTOMATIC_PIX_WAS_CONFIRMED

Este evento tem como objetivo informar que o agendamento com Pix automático foi confirmado.

Nome	Tipo	Descrição
`notification`	`string`	Identificador do tipo de notificação que deve ser enviada.
`notificationRule`	`string`	Descrição da regra de envio da notificação.
`consentUuid`	`string`	ID do consentimento associado ao pagamento.
`paymentId`	`string`	ID único do pagamento recorrente de Pix automático do Open Finance.
`endToEndId`	`string`	ID único de ponta a ponta da transação de pagamento de Pix automático do Open Finance.
`paymentDate`	`string`	Data do pagamento agendado de Pix automático do Open Finance.
`amount`	`object`	Objeto que contém informações sobre a transação.
`amount.value`	`number`	Valor da transação.
`amount.currency`	`string`	Sigla da moeda utilizada.
`maximumAmount`	`object`	Objeto que contém informações sobre o valor máximo do pagamento agendado de Pix automático do Open Finance.
`maximumAmount.value`	`number`	Valor máximo do pagamento agendado de Pix automático do Open Finance.
`maximumAmount.currency`	`string`	Sigla da moeda utilizada.
`fixedAmount`	`object`	Objeto que contém informações sobre o valor fixo do pagamento agendado de Pix automático do Open Finance.
`fixedAmount.value`	`number`	Valor fixo do pagamento agendado de Pix automático do Open Finance.
`fixedAmount.currency`	`string`	Sigla da moeda utilizada.
`additionalInformation`	`string`	Informações adicionais do pagamento agendado de Pix automático do Open Finance.
`creditorName`	`string`	Nome do recebedor da transação.
`debtor`	`object`	Objeto que contém informações sobre o pagador da transação.
`debtor.document`	`object`	Objeto que contém informações sobre o documento do pagador da transação.
`debtor.document.value`	`string`	Número do documento.
`debtor.document.type`	`string`	Tipo de documento (`CPF` ou `CNPJ`).
`debtor.name`	`string`	Nome do pagador da transação.
`debtor.account`	`object`	Objeto que contém informações sobre a conta do pagador da transação.
`debtor.account.branch`	`string`	Número da agência.
`debtor.account.number`	`string`	Número da conta.
`debtor.account.type`	`string`	Tipo de conta, que pode ser `"CHECKING"` (corrente), `"SALARY"` (salário), `"SAVINGS"` (poupança) ou `"PAYMENT"` (pagamento).
`debtor.account.bank`	`object`	Objeto que contém informações sobre o banco do pagador da transação.
`debtor.account.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco pagador da transação.
`debtor.account.bank.code`	`string`	Código do banco.
`debtor.account.bank.name`	`string`	Nome do banco.
`paymentStatus`	`string`	Status atual do pagamento agendado de Pix automático do Open Finance.
`hasRetry`	`string`	Indica se houve retry.
`companyKey`	`string`	Chave que identifica o parceiro dentro do Banco liquidante.
`initiatingPartyOrganisationIdentification`	`string`	ID da empresa que está realizando a iniciação de pagamento.

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplo de payload

{
 "entityId": "E99999001202405281500EiJoG2G14GV",
 "companyKey": "HIPERBANCO_SANDBOX",
 "idempotencyKey": "6e1d2f05-28aa-411d-9da2-71dee91c5fdf",
 "context": "Openfinance",
 "name": "OPENFINANCE_AUTOMATIC_PIX_WAS_CONFIRMED",
 "timestamp": "2025-09-04T17:14:14.7802996Z",
 "correlationId": "04b5d425-f43a-48a2-bbc6-e42b4b26e6dd",
 "data": {
    "notification": "CONCLUSAO_AGENDAMENTO",
    "notificationRule": "Mensagem enviada após a conclusão do fluxo de agendamento.",
    "consentUuid": "urn:bancobv:08fff16a-f90a-4ab4-9183-17a5692c9cbe",
    "paymentId": "f9c8e473-e699-4fc7-bd98-f7ad36e6e392",
    "endToEndId": "E99999001202405281500EiJoG2G14GV",
    "paymentDate": "2025-06-19",
    "amount": {
       "value": 40.00,
       "currency": "BRL"
    },
    "maximumAmount": {
       "value": 50.00,
       "currency": "BRL"
    },
    "fixedAmount": {
       "value": 60.00,
       "currency": "BRL"
    },
    "additionalInformation": "Conta de luz",
    "creditorName": "Companhia Energética do Nordeste",
    "debtor": {
       "document": {
          "value": "12345678000195",
          "type": "CNPJ"
       },
       "name": "Carlos Eduardo",
       "account": {
          "branch": "0001",
          "number": "987654321",
          "type": "CACC",
          "bank": {
             "ispb": "13140088",
             "code": "332",
             "name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento"
          }
       }
    },
    "paymentStatus": "RCVD",
    "hasRetry": "true",
    "companyKey": "ENERGIA_NE_001",
    "initiatingPartyOrganisationIdentification": "ORG987654321"
 },
 "licenses": [
    {
       "id": "25bcb44c-992c-4cfa-98ef-d344c1ce838a",
       "provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
       "types": [
          "Banking"
       ]
    }
 ],
 "licenseUuid": "25bcb44c-992c-4cfa-98ef-d344c1ce838a",
 "version": "1"
}

❗️
Atenção
O webhook OPENFINANCE_AUTOMATIC_PIX_WAS_CONFIRMED não substitui o evento PIX_CASHOUT_WAS_COMPLETED. Ele apenas indica que o agendamento do PIX foi confirmado com sucesso, sem garantir que o pagamento foi concluído.

⚠️
Importante
O evento PIX_CASHOUT_WAS_COMPLETED deve ser consumido para confirmar que o pagamento foi concluído e o valor debitado da conta do usuário. Somente após o recebimento deste evento a transação deverá ser exibida no extrato do cliente.

OPENFINANCE_AUTOMATIC_PIX_WAS_FAILED

Este evento tem como objetivo informar que o agendamento com Pix automático falhou.

Nome	Tipo	Descrição
`notification`	`string`	Identificador do tipo de notificação que deve ser enviada.
`notificationRule`	`string`	Descrição da regra de envio da notificação.
`consentUuid`	`string`	ID do consentimento associado ao pagamento.
`paymentId`	`string`	ID único do pagamento recorrente de Pix automático do Open Finance.
`endToEndId`	`string`	ID único de ponta a ponta da transação de pagamento de Pix automático do Open Finance.
`paymentDate`	`string`	Data do pagamento agendado de Pix automático do Open Finance.
`amount`	`object`	Objeto que contém informações sobre a transação.
`amount.value`	`number`	Valor da transação.
`amount.currency`	`string`	Sigla da moeda utilizada.
`maximumAmount`	`object`	Objeto que contém informações sobre o valor máximo do pagamento agendado de Pix automático do Open Finance.
`maximumAmount.value`	`number`	Valor máximo do pagamento agendado de Pix automático do Open Finance.
`maximumAmount.currency`	`string`	Sigla da moeda utilizada.
`fixedAmount`	`object`	Objeto que contém informações sobre o valor fixo do pagamento agendado de Pix automático do Open Finance.
`fixedAmount.value`	`number`	Valor fixo do pagamento agendado de Pix automático do Open Finance.
`fixedAmount.currency`	`string`	Sigla da moeda utilizada.
`additionalInformation`	`string`	Informações adicionais do pagamento agendado de Pix automático do Open Finance.
`creditorName`	`string`	Nome do recebedor da transação.
`debtor`	`object`	Objeto que contém informações sobre o pagador da transação.
`debtor.document`	`object`	Objeto que contém informações sobre o documento do pagador da transação.
`debtor.document.value`	`string`	Número do documento.
`debtor.document.type`	`string`	Tipo de documento (`CPF` ou `CNPJ`).
`debtor.name`	`string`	Nome do pagador da transação.
`debtor.account`	`object`	Objeto que contém informações sobre a conta do pagador da transação.
`debtor.account.branch`	`string`	Número da agência.
`debtor.account.number`	`string`	Número da conta.
`debtor.account.type`	`string`	Tipo de conta, que pode ser `"CHECKING"` (corrente), `"SALARY"` (salário), `"SAVINGS"` (poupança) ou `"PAYMENT"` (pagamento).
`debtor.account.bank`	`object`	Objeto que contém informações sobre o banco do pagador da transação.
`debtor.account.bank.ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco pagador da transação.
`debtor.account.bank.code`	`string`	Código do banco.
`debtor.account.bank.name`	`string`	Nome do banco.
`paymentStatus`	`string`	Status atual do pagamento agendado de Pix automático do Open Finance.
`hasRetry`	`string`	Indica se houve retry.
`companyKey`	`string`	Chave que identifica o parceiro dentro do Banco liquidante.
`initiatingPartyOrganisationIdentification`	`string`	ID da empresa que está realizando a iniciação de pagamento.

Payload do evento

O payload abaixo exemplifica a estrutura do evento que deverá ser recebido pelo parceiro. Clique na seta para expandi-lo:

Exemplo de payload

{
 "entityId": "E01858774202508151311LMZH7LncQhI",
 "companyKey": "HIPERBANCO_SANDBOX",
 "idempotencyKey": "da98c1c9-c41c-4a32-a094-898087562b21",
 "context": "Openfinance",
 "name": "OPENFINANCE_AUTOMATIC_PIX_WAS_FAILED",
 "timestamp": "2025-09-04T18:30:23.8838667Z",
 "correlationId": "ee23da93-dae3-4777-ac91-96ce750ca944",
 "data": {
    "notification": "PAGAMENTO_DIVERGENTE_CONSENTIMENTO ",
    "notificationRule": "Deve ser enviado sempre que houver uma solicitação de pagamento que excede a configuração do consentimento.",
    "consentUuid": "urn:hiperbanco:5be08606-7962-4c4e-8492-71a792ccbad8",
    "paymentId": "10f3c5af-6045-4095-8db4-aad90a205958",
    "endToEndId": "E01858774202508151311LMZH7LncQhI",
    "paymentDate": "2025-09-03",
    "amount": {
       "value": 0.50,
       "currency": "BRL"
    },
    "additionalInformation": "Conformance Suite Test",
    "creditorName": "LIKSTROM ENGENHARIA INDUSTRIA E COMERCIO LTDA",
    "debtor": {
       "document": {
          "value": "01234567890",
          "type": "CPF"
       },
       "name": "Carlos Eduardo",
       "account": {
          "branch": "0001",
          "number": "987654321",
          "type": "CACC",
          "bank": {
             "ispb": "13140088",
             "code": "332",
             "name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento"
          }
       }
    },
    "paymentStatus": "RJCT",
    "hasRetry": "false",
    "companyKey": "ENERGIA_NE_001",
    "initiatingPartyOrganisationIdentification": "44471172000119"
 },
 "licenses": [
    {
       "id": "25bcb44c-992c-4cfa-98ef-d344c1ce838a",
       "provider": "ACESSO SOLUÇÕES DE PAGAMENTO S.A. - INSTITUIÇÃO DE PAGAMENTO",
       "types": [
          "Banking"
       ]
    }
 ],
 "licenseUuid": "25bcb44c-992c-4cfa-98ef-d344c1ce838a",
 "version": "1"
}