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 por push notification 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 doc do Parceiro.

Eventos de notificação para Pix automático
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 IEventNotification.

Nome	Tipo	Descrição
`entityId`	`string`	Identificador da entidade emissora do evento. Portanto, ele 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 Bankly.
`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 a 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. Por exemplo, o tempo de solicitação e o tempo de resposta da operação.
`data`	`object`	Entidade relacionada ao ID, que varia conforme o evento. Por exemplo, quando se trata de um evento de conta, o `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`.

Notificação de confirmação de autorização de Pix automático

Nome do Evento: OPENFINANCE_AUTOMATIC_PIX_WAS_CONFIRMED

Versão: 1.0.0

Tipo: EXTERNO

Tópico: bankly.event.openfinance.payment.pushnotification

Descrição:

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.
`maximumAmoun.value`	`number`	Valor máximo do pagamento agendado de pix automático do Open Finance.
`maximumAmoun.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" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de 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 Bankly.
`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:

{
	"entityId": "E99999001202405281500EiJoG2G14GV",
	"companyKey": "ENERGIA_NE_001",
	"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"
}

Notificação de falha de autorização de Pix automático

Nome do Evento: OPENFINANCE_AUTOMATIC_PIX_WAS_FAILED

Versão: 1.0.0

Tipo: EXTERNO

Tópico: `bankly.event.openfinance.payment.pushnotification``

Descrição:

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.
`maximumAmoun.value`	`number`	Valor máximo do pagamento agendado de pix automático do Open Finance.
`maximumAmoun.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" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de 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 Bankly.
`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": "ENERGIA_NE_001",
	"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:bankly: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"
}