Pix

Neste contexto, os eventos se referem a transferência (cash-out), recebimento (cash-in) e devolução de valores (refund) via Pix.

Dados dos eventos

PIX_CASH_OUT_ACCOUNT

Este evento sinaliza a saída de valores de uma conta via Pix.

Campos retornados

Nome	Tipo	Descrição
`aggregateId`	`string`	Valor correspondente ao `authenticationCode`, retornado na requisição de transferência via Pix. O formato do valor será: PIX_TRANSACTION_ID_authenticationCode. Exemplo: “PIX_TRANSACTION_ID_95bc3705-11ce-4b80-86be-94e3b13c643c”.
`type`	`string`	Tipo de evento, que pode ser "INFO", "TRANSACTION", "ACTION" ou "BACKOFFICE".
`category`	`string`	Neste contexto, esse campo informará o valor “EletronicTransfers”.
`documentNumber`	`string`	Número de documento do cliente titular da conta que realizou o Pix.
`bankBranch`	`string`	Agência bancária do cliente.
`bankAccount`	`string`	Número da conta.
`amount`	`number`	Valor transacionado.
`index`	`string`	Índice do evento pra facilitar uma busca por um grupo de eventos. Exemplo: feed-2023-8, feed-2023-7.
`name`	`string`	Nome do evento.
`timestamp`	`string`	Data e a hora em que o evento ocorreu.
`data`	`object`	Objeto que contém os dados da transação e de seu recebedor.
`data.AuthenticationCode`	`string`	Código identificador da transação.
`data.EndToEndId`	`string`	Identificador único do Pix.
`data.TransactionDate`	`string`	Data da transação.
`data.InitializationType`	`string`	Modo pelo qual ocorreu a transação: `key`, no caso de chave de endereçamento Pix, `staticQrCode` ou `dynamicQrCode`, no caso de QR Codes, `Manual`, `Automatic` quando se tratar de uma transação do pix automático, `InitiationService` quando for uma transação iniciada por openFinance.
`data.AddressKey`	`string`	Valor da chave de endereçamento.
`data.AddressKeyType`	`string`	Tipo de chave de endereçamento, o qual pode ser: CPF, CNPJ, EMAIL, PHONE ou EVP.
`data.Description`	`string`	Descrição do pagamento.
`data.Channel`	`string`	Canal pelo qual a transação ocorreu.
`data.Amount`	`number`	Valor transacionado.
`data.Recipient`	`object`	Objeto que contém os dados referentes ao recebedor da transação.
`data.Recipient.Document`	`string`	Número do documento do recebedor.
`data.Recipient.DocumentType`	`string`	Tipo de documento, o qual pode ser CPF ou CNPJ.
`data.Recipient.Name`	`string`	Nome do recebedor.
`data.Recipient.BankBranch`	`string`	Número da agência bancária do recebedor.
`data.Recipient.BankAccount`	`string`	Número da conta.
`data.Recipient.BankAccountType`	`string`	Tipo de conta, o qual pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
`data.Recipient.BankIspb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.Recipient.BankName`	`string`	Nome do banco.
`data.Recipient.BankCompe`	`string`	Código do banco.
`data.ScheduledPaymentDate`	`string`	Em caso de Pix agendado, indica a data do agendamento.
`data.AmountDetails`	`array`	Lista que contém detalhes dos valores em caso de Pix saque e Pix troco.
`data.AmountDetails.Amount`	`number`	Valor do saque ou do troco.
`data.AmountDetails.AmountDetailType`	`number`	Em caso de Pix saque, o campo retornará 0. Para Pix troco, o campo retornará 1.
`data.WithdrawalProviderIspb`	`string`	Em caso de Pix saque e Pix troco, esse campo trará o número de ISPB do facilitador de serviço de saque.
`data.WithdrawalAgentType`	`string`	Em caso de Pix saque e Pix troco, esse campo trará o tipo de estabelecimento agente do saque.
`status`	`string`	O status "ACTIVE" indicará que o cash-out está em processamento ou foi realizado com sucesso. Caso contrário, o status estará como "CANCELED".

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

{
  "aggregateId": "PIX_TRANSACTION_ID_1fad75c3-0422-4399-bfb9-92981eecb7dd",
  "type": "TRANSACTION",
  "category": "EletronicTransfers",
  "description": "Pix cashout via Key",
  "documentNumber": "47742663023",
  "bankBranch": "0001",
  "bankAccount": "15164",
  "amount": -363.87,
  "index": "cash-out",
  "name": "PIX_CASH_OUT_ACCOUNT",
  "timestamp": "2023-08-24T20:34:53.4104283Z",
    "data": {
      "AuthenticationCode": "1fad75c3-0422-4399-bfb9-92981eecb7dd",
      "EndToEndId": "E1314008820230824203347161657050",
      "TransactionDate": "2023-08-24T20:34:58.9956484Z",
      "InitializationType": "DynamicQrCode",
      "AddressKey": "4004901d-bd85-4769-8e52-cb4c42c506dc",
      "AddressKeyType": "EVP",
      "Description": "Pix cashout via Key",
      "Channel": "SPI",
      "Amount": -363.87,
      "Recipient": {
        "Document": "34183937000161",
        "DocumentType": "CNPJ",
        "Name": "Editora Floresta",
        "BankBranch": "0001",
        "BankAccount": "422316",
        "BankAccountType": "CHECKING",
        "BankIspb": "000",
        "BankName": null,
        "BankCompe": null
      },
      "ScheduledPaymentDate": null,
      "AmountDetails": [
        {
          "Amount": 138.2,
          "AmountDetailType": 0
        },
        {
          "Amount": 225.67,
          "AmountDetailType": 1
        }
      ],
      "WithdrawalProviderIspb": "99999008",
      "WithdrawalAgentType": "Store"
    },
    "status": "ACTIVE"
}

PIX_CASH_IN_ACCOUNT

Este evento sinaliza a entrada de valores em uma conta via Pix.

Campos retornados

Nome	Tipo	Descrição
`aggregateId`	`string`	Identificador único do Pix recebido.
`type`	`string`	Tipo de evento , o qual pode ser "INFO", "TRANSACTION", "ACTION" ou "BACKOFFICE”.
`category`	`string`	Neste contexto, esse campo informará o valor “EletronicTransfers”.
`documentNumber`	`string`	Número de documento do cliente.
`bankBranch`	`string`	Agência bancária do cliente.
`bankAccount`	`string`	Número da conta.
`amount`	`number`	Valor transacionado.
`index`	`string`	Índice do evento pra facilitar uma busca por um grupo de eventos. Exemplo: feed-2023-8, feed-2023-7.
`name`	`string`	Nome do evento.
`timestamp`	`string`	Data e a hora em que o evento ocorreu.
`data`	`object`	Objeto que contém os dados da transação.
`data.DepositTransactionId`	`string`	Código identificador da transação em caso de devolução.
`data.ControlNumber`	`string`	Identificador da transação. Neste evento, esse campo retornará nulo.
`data.TransactionAmount`	`number`	Valor transacionado.
`data.ClearingAmount`	`number`	Valor liberado na conta.
`data.OverLimitAmount`	`number`	Valor excedido no limite para cash-in.
`data.AddressKey`	`string`	Valor da chave de endereçamento.
`data.Description`	`string`	Descrição do pagamento.
`data.Channel`	`string`	Canal pelo qual a transação ocorreu.
`data.SenderAccount`	`object`	Objeto que contém os dados referentes à conta e ao pagador da transação
`data.SenderAccount.Agency`	`string`	Número da agência bancária do pagador.
`data.SenderAccount.Account`	`string`	Número da conta.
`data.SenderAccount.Document`	`string`	Número do documento do pagador.
`data.SenderAccount.IspbNumber`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.SenderAccount.Name`	`string`	Nome do banco.
`data.RecipientAccount`	`object`	Objeto que contém os dados referentes à conta e ao recebedor da transação.
`data.RecipientAccount.Agency`	`string`	Número da agência bancária do recebedor.
`data.RecipientAccount.Account`	`string`	Número da conta.
`data.RecipientAccount.Document`	`string`	Número do documento do recebedor.
`data.RecipientAccount.Ispb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.RecipientAccount.Name`	`string`	Nome do recebedor.
`data.Recipient.BankName`	`string`	Nome do banco.
`data.EndToEndId`	`string`	Identificador único da transação Pix. Ele é utilizado quando o parceiro realiza um pagamento ou transferência via Pix.
`data.PixTransactionId`	string	Identificador do Pix gerado internamente em nosso sistema.
`AmountDetails`	array	Lista que contém detalhes dos valores em caso de Pix saque e Pix troco.
`WithdrawalProviderIspb`	`string`	Em caso de Pix saque e Pix troco, esse campo trará o número de ISPB do facilitador de serviço de saque.
`WithdrawalAgentType`	`string`	Em caso de Pix saque e Pix troco, esse campo trará o tipo de estabelecimento agente do saque.
`data.IsPixDeposit`	`boolean`	Campo que indica se o valor foi recebido via Pix.
`AuthenticationCodeExternal`	`string`	Campo obsoleto, que retornará nulo.
`IsTaxDeposit`	`boolean`	Campo obsoleto, que retornará false.
`IsTaxRefundDeposit`	`boolean`	Campo obsoleto, que retornará false.
`data.CorrelationId`	`string`	Identificador da transação utilizado para a análise de fluxo.
`data.Document`	`string`	Número do documento do recebedor da transação.
`data.CompanyKey`	`string`	Chave que identifica o parceiro dentro do Bankly.
`data.EventDateTime`	`string`	Data e a hora em que o evento ocorreu.
`status`	`string`	O status "ACTIVE" indicará que o cash-out está em processamento ou foi realizado com sucesso. Caso contrário, o status estará como "CANCELED".

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

{
  "aggregateId": "PIX_TRANSACTION_ID_f2a7f1ef-833a-4afa-ae6d-b71bafe25d3a",
  "type": "TRANSACTION",
  "category": "EletronicTransfers",
  "documentNumber": "47742663023",
  "bankBranch": "0001",
  "bankAccount": "15164",
  "amount": 1.0,
  "index": "cash-in",
  "name": "PIX_CASH_IN_ACCOUNT",
  "timestamp": "2021-04-13T15:07:46+00:00",
  "data": {
      "DepositTransactionId": "f2a7f1ef-833a-4afa-ae6d-b71bafe25d3a",
      "ControlNumber": null,
      "TransactionAmount": 1,
      "ClearingAmount": 1,
      "OverLimitAmount": 0,
      "AddressKey": "20820498092",
      "Description": "Description",
      "Channel": "INTERNAL_SPI",
      "SenderAccount": {
          "Agency": "0001",
          "Account": "540108",
          "Document": "09992220074",
          "IspbNumber": "13140088",
          "Name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento"
      },
      "RecipientAccount": {
        "Agency": "0001",
        "Account": "15164",
        "Document": "47742663023",
        "IspbNumber": "13140088",
        "Name": "Acesso Soluções De Pagamento SA - Instituição de Pagamento"
      },
      "EndToEndId": "E18236120202103311331s0000951O3S",
      "PixTransactionId": "00000000-0000-0000-0000-000000000000",
			"AmountDetails": [],
      "WithdrawalProviderIspb": null,
      "WithdrawalAgentType": null,
      "IsPixDeposit": true,
			"AuthenticationCodeExternal": null,
      "IsTaxDeposit": false,
      "IsTaxRefundDeposit": false,
      "CorrelationId": "e0baba13-a87f-4c0a-b494-76e8e8f33567",
      "Document": "00000000000",
      "CompanyKey": "BANKLY",
      "EventDateTime": "2021-04-13T15:07:46+00:00"
  },
	"status": "ACTIVE"
}

PIX_CASH_OUT_REFUND_ACCOUNT

Este evento sinaliza a saída de valores de uma conta para realizar a devolução de um montante recebido via Pix.

Campos retornados

Nome	Tipo	Descrição
`aggregateId`	`string`	Valor correspondente ao `authenticationCode`, retornado na requisição de transferência via Pix. O formato do valor será: PIX_TRANSACTION_ID_authenticationCode. Exemplo: “PIX_TRANSACTION_ID_95bc3705-11ce-4b80-86be-94e3b13c643c”.
`type`	`string`	Tipo de evento , o qual pode ser "INFO", "TRANSACTION", "ACTION" ou "BACKOFFICE”.
`category`	`string`	Neste contexto, esse campo informará o valor “EletronicTransfers”.
`description`	`string`	Descrição da transação.
`documentNumber`	`string`	Número de documento do cliente.
`bankBranch`	`string`	Agência bancária do cliente.
`bankAccount`	`string`	Número da conta.
`amount`	`number`	Valor transacionado.
`index`	`string`	Índice do evento pra facilitar uma busca por um grupo de eventos. Exemplo: feed-2023-8, feed-2023-7.
`name`	`string`	Nome do evento.
`timestamp`	`string`	Data e a hora em que o evento ocorreu.
`data`	`object`	Objeto que contém os dados da transação e de seu recebedor.
`data.AuthenticationCodeOriginal`	`string`	Código identificador da transação original.
`data.EndToEndIdOriginal`	`string`	Identificador único do Pix da transação original.
`data.RefundCode`	`string`	Código da devolução.
`data.RefundReason`	`string`	Motivo da devolução descrito pelo cliente.
`data.TotalRefundedAmount`	`number`	Valor total devolvido para a conta de origem.
`data.AuthenticationCode`	`string`	Código identificador da transação de devolução.
`data.EndToEndId`	`string`	Identificador único do Pix da transação de devolução.
`data.TransactionDate`	`string`	Data da transação de devolução.
`data.InitializationType`	`string`	Modo pelo qual ocorreu a transação: "key", no caso de chave de endereçamento Pix, "staticQrCode" ou "dynamicQrCode", no caso de QR Codes, e "Manual".
`data.AddressKey`	`string`	Valor da chave de endereçamento.
`data.AddressKeyType`	`string`	Tipo de chave de endereçamento, o qual pode ser: CPF, CNPJ, EMAIL, PHONE ou EVP.
`data.Description`	`string`	Descrição do pagamento.
`data.Channel`	`string`	Canal pelo qual a transação ocorreu.
`data.Amount`	`number`	Valor transacionado.
`data.Recipient`	`object`	Objeto que contém os dados referentes ao recebedor da transação.
`data.Recipient.Document`	`string`	Número do documento do recebedor.
`data.Recipient.DocumentType`	`string`	Tipo de documento, o qual pode ser CPF ou CNPJ.
`data.Recipient.Name`	`string`	Nome do recebedor.
`data.Recipient.BankBranch`	`string`	Número da agência bancária do recebedor.
`data.Recipient.BankAccount`	`string`	Número da conta.
`data.Recipient.BankAccountType`	`string`	Tipo de conta, o qual pode ser "CHECKING" (conta corrente), "SALARY" (conta salário), "SAVINGS" (poupança) e "PAYMENT" (conta de pagamento).
`data.Recipient.BankIspb`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.Recipient.BankName`	`string`	Nome do banco.
`data.Recipient.BankCompe`	`string`	Código do banco.
`status`	`string`	O status "ACTIVE" indicará que o cash-out está em processamento ou foi realizado com sucesso. Caso contrário, o status estará como "CANCELED".

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

[
  {
    "aggregateId": "PIX_TRANSACTION_ID_18f47236-06f7-4752-b46a-dfc25748f8e6",
    "type": "TRANSACTION",
    "category": "EletronicTransfers",
    "description": "Teste",
    "documentNumber": "47742663023",
    "bankBranch": "0001",
    "bankAccount": "15164",
    "amount": -300.0,
    "index": "cash-out",
    "name": "PIX_CASH_OUT_REFUND_ACCOUNT",
    "timestamp": "2021-09-29T21:28:16.9478046Z",
    "data": {
      "AuthenticationCodeOriginal": "75222074-a91a-4260-a03c-b6ccceaabc07",
      "EndToEndIdOriginal": "E0856170120210916004400000O0000",
      "RefundCode": "BE08",
      "RefundReason": "Payment need to be refunded due to different documents.",
      "TotalRefundedAmount": 300,
      "AuthenticationCode": "18f47236-06f7-4752-0000-dfc257480000",
      "EndToEndId": "D1314008820210000000017256401261",
      "TransactionDate": "2021-09-29T21:28:25.223092Z",
      "InitializationType": "Manual",
      "AddressKey": "000007-265e-4dab-bf35-b5f04eb098fd",
      "AddressKeyType": "EVP",
      "Description": "Payment need to be refunded due to different documents.",
      "Channel": "SPI",
      "Amount": -300,
      "Recipient": {
        "Document": "09992220074",
        "DocumentType": "CPF",
        "Name": "Quitéria Maria de Jesus",
        "BankBranch": "0001",
        "BankAccount": "540108",
        "BankAccountType": "CHECKING",
        "BankIspb": "13140088",
        "BankName": "Acesso Soluções De Pagamento SA - Instituição de Pagamento",
        "BankCompe": "322"
      }
    },
    "status": "ACTIVE"
  }
]

PIX_REFUND_ACCOUNT

Este evento sinaliza o recebimento por devolução de um valor que havia sido transacionado via Pix.

Campos retornados

Nome	Tipo	Descrição
`aggregateId`	`string`	Identificador único do Pix recebido.
`type`	`string`	Tipo de evento, o qual pode ser "INFO", "TRANSACTION", "ACTION" ou "BACKOFFICE”.
`category`	`string`	Neste contexto, esse campo informará o valor “EletronicTransfers”.
`documentNumber`	`string`	Número de documento do cliente.
`bankBranch`	`string`	Agência bancária do cliente.
`bankAccount`	`string`	Número da conta.
`amount`	`number`	Valor transacionado.
`index`	`string`	Índice do evento pra facilitar uma busca por um grupo de eventos. Exemplo: feed-2023-8, feed-2023-7.
`name`	`string`	Nome do evento.
`timestamp`	`string`	Data e a hora em que o evento ocorreu.
`data`	`object`	Objeto que contém os dados da transação.
`data.DepositTransactionId`	`string`	Código identificador da transação original.
`data.TransactionAmount`	`number`	Valor transacionado.
`data.Description`	`string`	Descrição da transação.
`data.Reason`	`string`	Motivo da devolução, o qual pode ser “BANK_RETURN” (o banco destino realizou a devolução) e “SPB_ERROR” (erro por parte do canal).
`data.Channel`	`string`	Canal pelo qual a transação ocorreu.
`data.ControlNumber`	`string`	Identificador da transação. Neste evento, esse campo retornará nulo.
`data.ControlNumberOriginal`	`string`	Identificador da transação original. Neste evento, esse campo retornará nulo.
`data.SenderAccount`	`object`	Objeto que contém os dados referentes ao pagador da transação.
`data.SenderAccount.Agency`	`string`	Número da agência bancária do pagador.
`data.SenderAccount.Account`	`string`	Número da conta.
`data.SenderAccount.Document`	`string`	Número do documento do pagador.
`data.SenderAccount.IspbNumber`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.SenderAccount.Name`	`string`	Nome do pagador da transação.
`data.RecipientAccount`	`object`	Objeto que contém os dados referentes ao recebedor da transação.
`data.RecipientAccount.Agency`	`string`	Número da agência bancária do recebedor.
`data.RecipientAccount.Account`	`string`	Número da conta.
`data.RecipientAccount.Document`	`string`	Número do documento do recebedor.
`data.RecipientAccount.IspbNumber`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`data.RecipientAccount.Name`	`string`	Nome do recebedor da transação.
`data.EndToEndId`	`string`	Identificador único do Pix da transação de devolução.
`data.EndToEndIdOriginal`	`string`	Identificador único do Pix da transação original.
`data.PixTransactionId`	`string`	Identificador do Pix gerado internamente em nosso sistema.
`data.IsPixRefund`	`boolean`	Indica se a transação se refere a uma devolução.
`data.CorrelationId`	`string`	Identificador da transação utilizado para a análise de fluxo.
`data.Document`	`string`	Número do documento do titular da conta recebedora.
`data.CompanyKey`	`string`	Chave que identifica o parceiro dentro do Bankly.
`data.EventDateTime`	`string`	Data e a hora em que o evento ocorreu.
`status`	`string`	O status "ACTIVE" indicará que o cash-out está em processamento ou foi realizado com sucesso. Caso contrário, o status estará como "CANCELED".

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

{
	"aggregateId": "PIX_TRANSACTION_ID_1d18a73e-ea28-4639-83ee-41a23961b8de",
	"type": "TRANSACTION",
	"category": "EletronicTransfers",
	"documentNumber": "47742663023",
	"bankBranch": "0001",
	"bankAccount": "15164",
	"amount": 0.01,
	"index": "feed-pix-refund-account-2021-4",
	"name": "PIX_REFUND_ACCOUNT",
	"timestamp": "2021-04-29T16:03:18+00:00",
	"data": {
		"DepositTransactionId": "1d18a73e-ea28-4639-83ee-41a23961b8de",
		"TransactionAmount": 0.01,
		"Description": "Devolução",
		"Reason": "BANK_RETURN",
		"Channel": "INTERNAL_SPI",
		"ControlNumber": null,
		"ControlNumberOriginal": null,
		"SenderAccount": {
			"Agency": "0001",
			"Account": "540108",
			"Document": "09992220074",
			"IspbNumber": "18236120",
			"Name": "Quitéria Maria de Jesus"
		},
		"RecipientAccount": {
			"Agency": "0001",
			"Account": "15164",
			"Document": "47742663023",
			"IspbNumber": "13140088",
			"Name": "Nísia Floresta"
		},
		"EndToEndId": "D18236120202104291603s0012014ZFM",
		"EndToEndIdOriginal": "E1314008820210429160237333204252",
		"PixTransactionId": "c3e287fa-ad7a-4780-95d3-ff5a3392e053",
		"IsPixRefund": true,
		"CorrelationId": "502a8fe8-d606-4187-a949-ec65f149822b",
		"Document": "47742663023",
		"CompanyKey": "BANKLY",
		"EventDateTime": "2021-04-29T16:03:18+00:00"
	},
    "status": "ACTIVE"
}

Código da devolução

Código	Descrição
BE08	Devolução de pagamento instantâneo devido a erro do PSP (Provedor de Serviços de Pagamento). Utilizado em caso de Mecanismo Especial de Devolução (MED).
FR01	Devolução de pagamento motivada por fundada suspeita de fraude. Utilizado em caso de Mecanismo Especial de Devolução (MED).
MD06	Devolução de pagamento instantâneo solicitada pelo usuário recebedor pagamento original.
SL02	Devolução motivada por um erro relacionado ao saque Pix.

Tipo de estabelecimento agente do saque

Tipo	Descrição
AGTEC1	Estabelecimento comercial
AGTOT	Outra espécie de pessoa jurídica que tenha como atividade principal ou secundária a prestação de serviços auxiliares a serviços financeiros ou afins ou correspondente no País (NR).
AGPSS	Participante do Pix que facilita o serviço de saque diretamente.