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

NomeTipoDescrição
aggregateIdstringValor 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”.
typestringTipo de evento, que pode ser INFO, TRANSACTION, ACTION OU BACKOFFICE.
categorystringNeste contexto, esse campo informará o valor “EletronicTransfers”.
documentNumberstringNúmero de documento do cliente titular da conta que realizou o Pix.
bankBranchstringAgência bancária do cliente.
bankAccountstringNúmero da conta.
amountnumberValor transacionado.
indexstringÍndice do evento pra facilitar uma busca por um grupo de eventos. Exemplo: feed-2023-8, feed-2023-7.
namestringNome do evento.
timestampstringData e a hora em que o evento ocorreu.
dataobjectObjeto que contém os dados da transação e de seu recebedor.
data.AuthenticationCodestringCódigo identificador da transação.
data.EndToEndIdstringIdentificador único do Pix.
data.TransactionDatestringData da transação.
data.InitializationTypestringModo 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.AddressKeystringValor da chave de endereçamento.
data.AddressKeyTypestringTipo de chave de endereçamento, que pode ser: CPF, CNPJ, EMAIL, PHONE ou EVP.
data.DescriptionstringDescrição do pagamento.
data.ChannelstringCanal pelo qual a transação ocorreu.
data.AmountnumberValor transacionado.
data.RecipientobjectObjeto que contém os dados referentes ao recebedor da transação.
data.Recipient.DocumentstringNúmero do documento do recebedor.
data.Recipient.DocumentTypestringTipo de documento, o qual pode ser CPF ou CNPJ.
data.Recipient.NamestringNome do recebedor.
data.Recipient.BankBranchstringNúmero da agência bancária do recebedor.
data.Recipient.BankAccountstringNúmero da conta.
data.Recipient.BankAccountTypestringTipo de conta, o qual pode ser CHECKING para conta corrente, SALARY para conta salário, SAVINGS para conta poupança e PAYMENT para conta de pagamento.
data.Recipient.BankIspbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.Recipient.BankNamestringNome do banco.
data.Recipient.BankCompestringCódigo do banco.
data.ScheduledPaymentDatestringEm caso de Pix agendado, indica a data do agendamento.
data.AmountDetailsarrayLista que contém detalhes dos valores em caso de Pix saque e Pix troco.
data.AmountDetails.AmountnumberValor do saque ou do troco.
data.AmountDetails.AmountDetailTypenumberEm caso de Pix saque, o campo retornará 0. Para Pix troco, o campo retornará 1.
data.WithdrawalProviderIspbstringEm caso de Pix saque e Pix troco, esse campo trará o número de ISPB do facilitador de serviço de saque.
data.WithdrawalAgentTypestringEm caso de Pix saque e Pix troco, esse campo trará o tipo de estabelecimento agente do saque.
statusstringstatus 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

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

NomeTipoDescrição
aggregateIdstringIdentificador único do Pix recebido.
typestringTipo de evento , o qual pode ser INFO, TRANSACTION, ACTION OU BACKOFFICE.
categorystringNeste contexto, esse campo informará o valor “EletronicTransfers”.
documentNumberstringNúmero de documento do cliente.
bankBranchstringAgência bancária do cliente.
bankAccountstringNúmero da conta.
amountnumberValor transacionado.
indexstringÍndice do evento pra facilitar uma busca por um grupo de eventos. Ex: feed-2023-8, feed-2023-7.
namestringNome do evento.
timestampstringData e a hora em que o evento ocorreu.
dataobjectObjeto que contém os dados da transação.
data.DepositTransactionIdstringCódigo identificador da transação em caso de devolução.
data.ControlNumberstringIdentificador da transação. Neste evento, esse campo retornará nulo.
data.TransactionAmountnumberValor transacionado.
data.ClearingAmountnumberValor liberado na conta.
data.OverLimitAmountnumberValor excedido no limite para cash-in.
data.AddressKeystringValor da chave de endereçamento.
data.DescriptionstringDescrição do pagamento.
data.ChannelstringCanal pelo qual a transação ocorreu.
data.SenderAccountobjectObjeto que contém os dados referentes à conta e ao pagador da transação
data.SenderAccount.AgencystringNúmero da agência bancária do pagador.
data.SenderAccount.AccountstringNúmero da conta.
data.SenderAccount.DocumentstringNúmero do documento do pagador.
data.SenderAccount.IspbNumberstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.SenderAccount.NamestringNome do banco.
data.RecipientAccountobjectObjeto que contém os dados referentes à conta e ao recebedor da transação.
data.RecipientAccount.AgencystringNúmero da agência bancária do recebedor.
data.RecipientAccount.AccountstringNúmero da conta.
data.RecipientAccount.DocumentstringNúmero do documento do recebedor.
data.RecipientAccount.IspbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.RecipientAccount.NamestringNome do recebedor.
data.Recipient.BankNamestringNome do banco.
data.EndToEndIdstringIdentificador único do Pix. Ele é utilizado quando o parceiro realiza um pagamento ou transferência via Pix.
data.PixTransactionIdstringIdentificador do Pix gerado internamente em nosso sistema.
AmountDetailsarrayLista que contém detalhes dos valores em caso de Pix saque e Pix troco.
WithdrawalProviderIspbstringEm caso de Pix saque e Pix troco, esse campo trará o número de ISPB do facilitador de serviço de saque.
WithdrawalAgentTypestringEm caso de Pix saque e Pix troco, esse campo trará o tipo de estabelecimento agente do saque.
data.IsPixDepositbooleanCampo que indica se o valor foi recebido via Pix.
AuthenticationCodeExternalstringCampo obsoleto, que retornará nulo.
IsTaxDepositbooleanCampo obsoleto, que retornará false.
IsTaxRefundDepositbooleanCampo obsoleto, que retornará false.
data.CorrelationIdstringIdentificador da transação utilizado para a análise de fluxo.
data.DocumentstringNúmero do documento do recebedor da transação.
data.CompanyKeystringChave que identifica o parceiro dentro do Bankly.
data.EventDateTimestringData e a hora em que o evento ocorreu.
statusstringstatus 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

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

NomeTipoDescrição
aggregateIdstringValor 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”.
typestringTipo de evento , o qual pode ser INFO, TRANSACTION, ACTION OU BACKOFFICE.
categorystringNeste contexto, esse campo informará o valor “EletronicTransfers”.
descriptionstringDescrição da transação.
documentNumberstringNúmero de documento do cliente.
bankBranchstringAgência bancária do cliente.
bankAccountstringNúmero da conta.
amountnumberValor transacionado.
indexstringÍndice do evento pra facilitar uma busca por um grupo de eventos. Ex: feed-2023-8, feed-2023-7.
namestringNome do evento.
timestampstringData e a hora em que o evento ocorreu.
dataobjectObjeto que contém os dados da transação e de seu recebedor.
data.AuthenticationCodeOriginalstringCódigo identificador da transação original.
data.EndToEndIdOriginalstringIdentificador único do Pix da transação original.
data.RefundCodestringCódigo da devolução.
data.RefundReasonstringMotivo da devolução descrito pelo cliente.
data.TotalRefundedAmountnumberValor total devolvido para a conta de origem.
data.AuthenticationCodestringCódigo identificador da transação de devolução.
data.EndToEndIdstringIdentificador único do Pix da transação de devolução.
data.TransactionDatestringData da transação de devolução.
data.InitializationTypestringModo 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.AddressKeystringValor da chave de endereçamento.
data.AddressKeyTypestringTipo de chave de endereçamento, que pode ser: CPF, CNPJ, EMAIL, PHONE ou EVP.
data.DescriptionstringDescrição do pagamento.
data.ChannelstringCanal pelo qual a transação ocorreu.
data.AmountnumberValor transacionado.
data.RecipientobjectObjeto que contém os dados referentes ao recebedor da transação.
data.Recipient.DocumentstringNúmero do documento do recebedor.
data.Recipient.DocumentTypestringTipo de documento, o qual pode ser CPF ou CNPJ.
data.Recipient.NamestringNome do recebedor.
data.Recipient.BankBranchstringNúmero da agência bancária do recebedor.
data.Recipient.BankAccountstringNúmero da conta.
data.Recipient.BankAccountTypestringTipo de conta, o qual pode ser CHECKING para conta corrente, SALARY para conta salário, SAVINGS para conta poupança e PAYMENT para conta de pagamento.
data.Recipient.BankIspbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.Recipient.BankNamestringNome do banco.
data.Recipient.BankCompestringCódigo do banco.
statusstringO 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

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

NomeTipoDescrição
aggregateIdstringIdentificador único do Pix recebido.
typestringTipo de evento, o qual pode ser INFO, TRANSACTION, ACTION OU BACKOFFICE.
categorystringNeste contexto, esse campo informará o valor “EletronicTransfers”.
documentNumberstringNúmero de documento do cliente.
bankBranchstringAgência bancária do cliente.
bankAccountstringNúmero da conta.
amountnumberValor transacionado.
indexstringÍndice do evento pra facilitar uma busca por um grupo de eventos. Ex: feed-2023-8, feed-2023-7.
namestringNome do evento.
timestampstringData e a hora em que o evento ocorreu.
dataobjectObjeto que contém os dados da transação.
data.DepositTransactionIdstringCódigo identificador da transação original.
data.TransactionAmountnumberValor transacionado.
data.DescriptionstringDescrição da transação.
data.ReasonstringMotivo 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.ChannelstringCanal pelo qual a transação ocorreu.
data.ControlNumberstringIdentificador da transação. Neste evento, esse campo retornará nulo.
data.ControlNumberOriginalstringIdentificador da transação original. Neste evento, esse campo retornará nulo.
data.SenderAccountobjectObjeto que contém os dados referentes ao pagador da transação.
data.SenderAccount.AgencystringNúmero da agência bancária do pagador.
data.SenderAccount.AccountstringNúmero da conta.
data.SenderAccount.DocumentstringNúmero do documento do pagador.
data.SenderAccount.IspbNumberstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.SenderAccount.NamestringNome do pagador da transação.
data.RecipientAccountobjectObjeto que contém os dados referentes ao recebedor da transação.
data.RecipientAccount.AgencystringNúmero da agência bancária do recebedor.
data.RecipientAccount.AccountstringNúmero da conta.
data.RecipientAccount.DocumentstringNúmero do documento do recebedor.
data.RecipientAccount.IspbNumberstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
data.RecipientAccount.NamestringNome do recebedor da transação.
data.EndToEndIdstringIdentificador único do Pix da transação de devolução.
data.EndToEndIdOriginalstringIdentificador único do Pix da transação original.
data.PixTransactionIdstringIdentificador do Pix gerado internamente em nosso sistema.
data.IsPixRefundbooleanIndica se a transação se refere a uma devolução.
data.CorrelationIdstringIdentificador da transação utilizado para a análise de fluxo.
data.DocumentstringNúmero do documento do titular da conta recebedora.
data.CompanyKeystringChave que identifica o parceiro dentro do Bankly.
data.EventDateTimestringData e a hora em que o evento ocorreu.
statusstringstatus 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

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ódigoDescrição
BE08Devoluçã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).
FR01Devolução de pagamento motivada por fundada suspeita de fraude. Utilizado em caso de Mecanismo Especial de Devolução (MED).
MD06Devolução de pagamento instantâneo solicitada pelo usuário recebedor pagamento original.
SL02Devolução motivada por um erro relacionado ao saque Pix.

Tipo de estabelecimento agente do saque

TipoDescrição
AGTEC1Estabelecimento comercial
AGTOTOutra 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).
AGPSSParticipante do Pix que facilita o serviço de saque diretamente.