Visão geral

Estrutura

Os eventos Bankly são organizados em listas e enviados ao parceiro no formato JSON. Cada evento possui a seguinte estrutura:

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 do Bankly.
`idempotencyKey`	`string`	Valor retornado para evitar eventos duplicados (em formato UUID).
`context`	`string`	Contexto em que o evento foi criado. Os possíveis contextos estão listados mais adiante nesta documentação.
`name`	`string`	Nome descritivo que identifica a operação realizada. Abaixo, você encontra a nomenclatura padrão dos eventos.
`timestamp`	`string`	Data e a hora em que o evento ocorreu, no formato ISO 3601 - UTC.
`correlationId`	`string`	Identificador que correlaciona todo o fluxo das operações.
`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.

🚧
Importante
Recomendamos que os parceiros observem a versão do evento a ser utilizado, pois, de forma a melhorar a experiência dos seus clientes, o Bankly está constantemente evoluindo seus produtos.

[
   {
      "entityId": "Id of the entity that raised the event",
      "companyKey": "Company Key of the entity that raised the event",
      "context": "Context of the service that raised the event",
      "name": "Event name",
      "timestamp": "Date when the event was raised",
      "correlationId": "For tracing",
      "version": "1",
      "metadata": {
         "key": "Complement event info"
      },
      "data": {
         "Bar": "Foo"
      }
   }
]

Exemplos

[
   {
      "entityId":"16d9ce8d-bf54-4433-ac4e-0000000000",
      "companyKey":"ACESSO",
      "idempotencyKey":"3b5d8309-cb7f-4b0d-8d35-0000000000",
      "context":"Ted",
      "name":"TED_CASH_IN_WAS_RECEIVED",
      "timestamp":"2022-01-11T13:06:24.2559021Z",
      "correlationId":"7ab145b5-f0a1-42af-b187-8dcb670b962c",
      "metadata":null,
      "data":{
         "authenticationCode":"16d9ce8d-bf54-4433-ac4e-0000000000",
         "amount":{
            "value":0.01,
            "currency":"BRL"
         },
         "recipient":{
            "document":{
               "value":"09992220074",
               "type":"CPF"
            },
            "type":"Maria Quitéria de Jesus",
            "name":"string",
            "account":{
               "branch":"0001",
               "number":"540108",
               "bank":{
                  "ispb":"13140088",
                  "code":"332"
               }
            }
         },
         "channel":{
            "name":"SPB",
            "sender":{
               "document":{
                  "value":"47742663023",
                  "type":"CPF"
               },
               "type":"Customer",
               "name":"Nísia Floresta",
               "account":{
                  "branch":"0001",
                  "number":"15164",
                  "bank":{
                     "ispb":"13140088"
                  }
               }
            },
            "controlNumber":"STR2022011100000000000"
         },
         "createdAt":"2022-01-09T13:06:24.2240368Z"
      }
   }
]

[
   {
      "entityId": "a79753ae-6d68-4e81-b4a4-14147063b12b",
      "idempotencyKey": "86447d19-687f-4fa8-80cf-a5aa406457b9",
      "companyKey": "ACESSO",
      "context": "Ted",
      "name": "TED_REFUND_WAS_RECEIVED",
      "timestamp": "2021-10-05T00:00:00.000Z",
      "correlationId": "61833e96-86ea-4248-9700-5fd08a00bcb2",
      "version": "1",
      "metadata": {
         "key": "Complement event info"
      },
      "data": {
         "amount": {
            "value": 0,
            "currency": "BRL"
         },
         "recipient": {
            "document": {
               "value": "12346789000",
               "type": "CPF"
            },
            "name": "string",
            "status": "APPROVED",
            "account": {
               "branch": "0001",
               "number": "965",
               "balance": {
                  "value": 0,
                  "currency": "BRL"
               },
               "status": "ACTIVE",
               "bank": {
                  "ispb": "12345678",
                  "code": "332",
                  "name": "Acesso Soluções Pagamentos S.A"
               }
            }
         },
         "channel": {
            "name": "SPB",
            "sender": {
               "document": {
                  "value": "12346789000",
                  "type": "CPF"
               },
               "name": "string",
               "status": "APPROVED",
               "account": {
                  "branch": "0001",
                  "number": "123456",
                  "bank": {
                     "ispb": "12345678",
                     "code": "123",
                     "name": "Test Bank"
                  }
               }
            },
            "ControlNumber": "ACB20211120000000002",
            "ControlNumberOriginal": "ACB20211120000000001"
         }
      }
   }
]

Contextos

Nome	Descrição
Pix	Agrupa todos os eventos relacionados a cash-in e cash-out, refunds (devoluções) e QR Codes Pix.
DICT	Agrupa todos os eventos relacionados a DICT e a pedidos de portabilidade e reivindicação de chaves Pix.
Boleto	Agrupa todos os eventos relacionados a boletos, como emissão, cancelamento, compensação etc.
Ted	Agrupa todos os eventos relacionados a cash-in, cash-out e refunds (devoluções) via TED.
Payment (Pagamento de contas)	Agrupa todos os eventos relacionados a pagamentos de contas, como criação, recebimento, confirmação e o cancelamento do pagamento, assim como falha na transação.
Document (Envio de documentos de Onboarding)	Agrupa todos os eventos relacionados ao recebimento e o processamento de imagens para Onboarding.
Account (Contas)	Agrupa todos os eventos relacionados à abertura e encerramento de contas (por solicitação do cliente, parceiro ou Bankly), assim como eventos referentes a bloqueio/desbloqueio judicial.
Authorization (Autorização, confirmação e 3DS)	Agrupa todos os eventos relacionados à autorização de transações com cartão, como expiração, confirmação, cancelamento da transação etc. Além disso, também existem eventos referentes à autorização 3DS.
Card (Cartão)	Agrupa todos os eventos relacionados a emissão do cartão, a alteração do status de rastreio e do status do cartão e a adição e remoção do cartão da carteira.
Credict (Crédito)	Agrupa todos os eventos relacionados ao processo de análise de crédito, a faturas e pagamentos em atraso, negativação, bloqueio do cartão e cancelamento do contrato de crédito do cliente.
Customer (Pessoa física)	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa física.
Business (Pessoa jurídica)	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa jurídica.
Invoice (Faturas)	Agrupa todos os eventos relacionados a criação de uma transação, processamento e fechamento de uma fatura e a realização do pagamento total ou proporcional da fatura.
Pocket	Agrupa todos os eventos relacionados a criação, mudança de usuário, encerramento, depósitos, resgates de valores e falhas nas transações com contas pockets.
Partner	Agrupa eventos que informam sobre a indisponibilidade em um ou mais serviços de uma feature e sobre a volta à normalidade do serviço.

Nomenclatura

Contexto Pix

Nome do evento (name)	Descrição
PIX_CASH_IN_WAS_RECEIVED	O valor foi recebido no core bancário Bankly.
PIX_CASH_IN_WAS_CLEARED	O valor foi liberado na conta destino.
PIX_REFUND_WAS_RECEIVED	O valor devolvido foi recebido no core bancário Bankly.
PIX_REFUND_WAS_CLEARED	O valor devolvido foi liberado na conta destino.
PIX_CASHOUT_WAS_COMPLETED	Pagamento via Pix finalizado.
PIX_CASHOUT_WAS_CANCELED	Pagamento via Pix cancelado. Nesse caso, o valor não sai da conta do pagador e, portanto, não ocorre estorno.
PIX_CASHOUT_WAS_UNDONE	Pagamento via Pix desfeito. A operação de transferência de valor ocorre, mas, devido a algum erro no recebedor, ela não pode ser completada. Nesse caso, acontece o estorno.
PIX_QRCODE_WAS_CREATED	Um QR Code para pagamento via Pix foi emitido.

Contexto Boleto

Nome do evento (name)	Descrição
BOLETO_CASH_IN_WAS_RECEIVED	O valor foi recebido no core bancário Bankly.
BOLETO_CASH_IN_WAS_CLEARED	O valor foi liberado na conta destino.
BOLETO_WAS_REGISTERED	O boleto está apto para pagamento.
BOLETO_WAS_CANCELLED_BY_RECIPIENT	O boleto foi cancelado pelo recebedor do pagamento.
BOLETO_WAS_CANCELLED_BY_DEADLINE	O boleto foi cancelado por decurso de prazo.

Contexto DICT

Nome do evento (name)	Descrição
PIX_CLAIM_WAS_ACKNOWLEDGED	O pedido de reivindicação foi reconhecido.
PIX_CLAIM_WAS_CONFIRMED	O pedido de reivindicação foi confirmado.
PIX_CLAIM_WAS_COMPLETED	O processo de reivindicação foi concluído.
PIX_CLAIM_WAS_CANCELED	O processo de reivindicação foi cancelado.
PIX_CLAIM_WAS_REGISTERED	Um cliente do parceiro Bankly registrou um pedido de reivindicação de posse/portabilidade para outra instituição.

Contexto TED

Nome do evento (name)	Descrição
TED_CASH_OUT_WAS_APPROVED	Transferência aprovada pela análise de antifraude.
TED_CASH_IN_WAS_RECEIVED	O valor foi recebido no core bancário Bankly.
TED_CASH_IN_WAS_CLEARED	O valor foi liberado na conta destino.
TED_REFUND_WAS_RECEIVED	O valor devolvido foi recebido no core bancário Bankly.
TED_REFUND_WAS_CLEARED	O valor devolvido foi liberado na conta destino.
TED_CASH_OUT_WAS_DONE	A transferência do valor foi realizada.
TED_CASH_OUT_WAS_REPROVED	A transação foi reprovada pela equipe de análise antifraude.
TED_CASH_OUT_WAS_UNDONE	A transação foi desfeita devido à reprovação pela equipe de análise antifraude.
TED_CASH_OUT_WAS_CANCELED	Transferência cancelada por falta de saldo na conta.

Contexto Payment (Pagamento de contas)

Nome do evento (name)	Descrição
BILL_PAYMENT_WAS_RECEIVED	O pagamento foi recebido.
BILL_PAYMENT_WAS_CREATED	O pagamento foi criado.
BILL_PAYMENT_WAS_CONFIRMED	O pagamento foi confirmado.
BILL_PAYMENT_HAS_FAILED	Houve falha no pagamento.
BILL_PAYMENT_WAS_CANCELLED	O pagamento foi cancelado.
BILL_PAYMENT_WAS_REFUSED	Pagamento recusado devido a problemas identificados após a sua confirmação. O valor foi estornado ao pagador.

Contexto Document (Envio de documentos de Onboarding)

Nome do evento (name)	Descrição
DOCUMENT_WAS_RECEIVED	A imagem do documento foi recebida, porém ela pode ainda não ter sido completamente analisada.
DOCUMENT_WAS_PROCESSED	A imagem do documento foi recebida e analisada.

Contexto Account (Contas)

Nome do evento (name)	Descrição
ACCOUNT_WAS_CREATED	A conta foi criada.
ACCOUNT_WAS_CLOSED	A conta foi encerrada tecnicamente.
ACCOUNT_WAS_LEGALLY_CLOSED	A conta foi encerrada legalmente. Neste caso, o Banco central foi informado do encerramento.
AMOUNT_WAS_BLOCKED	O valor foi bloqueado
AMOUNT_WAS_UNBLOCKED	O valor foi desbloqueado.
PAYMENT_ACCOUNT_WAS_LOCKED	A conta foi bloqueada.
PAYMENT_ACCOUNT_WAS_UNLOCKED	A conta foi desbloqueada.

Contexto Authorization (Autorização e confirmação)

Nome do evento (name)	Descrição
TRANSACTION_WAS_PROCESSED	A transação foi processada. Ela pode ter sido aprovada ou não.
TRANSACTION_WAS_REVERTED	A transação foi revertida parcial ou totalmente.
TRANSACTION_WAS_EXPIRED	O tempo de reserva de saldo da transação expirou e a transação foi revertida. Esse fluxo ocorre em transações pré-pagas.
CONFIRMATION_WAS_PROCESSED	A transação foi confirmada parcial ou totalmente.
CANCELATION_WAS_PROCESSED	A transação foi cancelada.
VOUCHER_WAS_PROCESSED	O voucher (crédito) foi lançado na conta do cliente.
PRE_AUTHENTICATION_WAS_RECEIVED	Após receber um pedido de pré-autenticação 3DS, o Bankly realizou uma análise antifraude para identificar a necessidade de criação de um desafio. Caso o resultado dessa análise tenha sido "challenge" (desafio), o evento PRE_AUTHENTICATION_CHALLENGE_WAS_REQUESTED será enviado para o parceiro.
PRE_AUTHENTICATION_CHALLENGE_WAS_REQUESTED	Um desafio foi requisitado. Após receber este evento, o parceiro deverá criar um desafio e enviá-lo a seu cliente para que ele possa confirmar a tentativa de compra.

Contexto Card (Cartão)

Nome do evento (name)	Descrição
CARD_WAS_ISSUED	O cartão foi emitido.
TRACKING_STATUS_CHANGED	Houve uma atualização no status de rastreio.
CARD_STATUS_WAS_MODIFIED	O status do cartão foi alterado.
CARD_WAS_ADDED_TO_WALLET	O cartão foi adicionado na carteira digital.
CARD_WAS_REMOVED_FROM_WALLET	O cartão foi removido da carteira digital.

Contexto Credit (Crédito)

Nome do evento (name)	Descrição
CREDIT_CARD_LIMIT_CREATED	Solicitação de limite de crédito criada.
CREDIT_CARD_LIMIT_APPROVED	Solicitação de limite de crédito aprovada.
CREDIT_CARD_LIMIT_REPROVED	Solicitação de limite de crédito reprovada de acordo com a política de crédito.
CREDIT_CARD_ANALYSIS_COMPLETED	A análise de crédito foi finalizada e pode ter sido aprovada ou reprovada.
CREDIT_CARD_ANALYSIS_EXPIRED	O período para o consentimento da análise expirou-se. Neste caso, é necessário solicitar uma nova análise.
CREDIT_CARD_CONTRACT_ACCEPTED	Contrato de limite de crédito aceito. Este evento sinaliza que o cliente aceitou a análise disponibilizada e assinou o contrato.
CREDIT_CARD_CONTRACT_BLOCKED	Contrato de crédito bloqueado devido à inadimplência por mais de 5 dias.
CREDIT_CARD_CONTRACT_CANCELLED	Contrato de crédito cancelado.
CREDIT_CARD_CONTRACT_UNBLOCKED	Contrato de crédito desbloqueado, pois o cliente quitou/negociou seu débito de inadimplência.
CREDIT_CARD_LIMIT_INCREASE_REQUESTED	Após reanálise, o aumento do limite de crédito do cliente foi solicitado.
CREDIT_CARD_LIMIT_INCREASE_APPROVED	Após reanálise, o aumento do limite de crédito do cliente foi aprovado.
CREDIT_CARD_LIMIT_INCREASE_ACCEPTED	O aumento do limite de crédito foi aceito. Este evento sinaliza que o cliente aceitou o aumento de limite de crédito e assinou o contrato.
CREDIT_CARD_LIMIT_INCREASE_REFUSED	Após reanálise, o aumento de limite de crédito do cliente foi recusado.
CREDIT_CARD_LIMIT_REDUCTION_REQUESTED	Após reanálise, a diminuição do limite é solicitada, para ocorrer 5 dias após a decisão.
CREDIT_CARD_LIMIT_REDUCTION_APPLIED	Após o tempo de requisição da redução de limite, a diminuição do limite é aplicada.
INVOICE_BILLING_WAS_OVERDUE	Fatura há X dias em atraso. Este evento informa há quantos dias a fatura está em atraso. Seu envio é diário até que a fatura seja paga.
INVOICE_BILLING_WAS_PAID	Pagamento realizado de fatura em atraso.
CUSTOMER_BAD_CREDIT_APPLY_REQUESTED	Solicitação de negativação do cliente realizada.
CUSTOMER_BAD_CREDIT_REMOVE_REQUESTED	Solicitação de remoção da negativação do cliente realizada.
CUSTOMER_BILLING_CREATED	Cliente enviado para um escritório parceiro de cobrança.
CONTRACT_CREDIT_BLOCK_REQUEST_CREATED	Solicitação de bloqueio do cartão realizada.
CONTRACT_CREDIT_UNBLOCK_REQUEST_CREATED	Solicitação de desbloqueio do cartão realizada.
CONTRACT_CREDIT_CANCELLMENT_REQUESTED	Solicitação de cancelamento do contrato de crédito do cliente realizada. Esta ação é irreversível.

Contexto Customer (Pessoa física)

Nome do evento (name)	Descrição
CUSTOMER_WAS_RECEIVED	A solicitação de cadastro do cliente foi recebida.
CUSTOMER_IN_ANALYSIS	O cadastro do cliente está em análise.
CUSTOMER_WAS_APPROVED	O cadastro do cliente foi aprovado.
CUSTOMER_WAS_REPROVED	O cadastro do cliente foi reprovado.
CUSTOMER_WAS_CANCELED	O cadastro do cliente foi cancelado.
CUSTOMER_WAS_REVOKED	O perfil do cadastro do cliente regrediu para simples.
CUSTOMER_WAS_BLOCKED	O cadastro do cliente foi bloqueado (na maioria dos casos, devido à fraude).
CUSTOMER_WAS_UPDATED	O cadastro do cliente pessoa física foi atualizado.

Contexto Business (Pessoa jurídica)

Nome do evento (name)	Descrição
BUSINESS_WAS_RECEIVED	A solicitação de cadastro do cliente foi recebida.
BUSINESS_WAS_APPROVED	O cadastro do cliente foi aprovado.
BUSINESS_WAS_REPROVED	O cadastro do cliente foi reprovado.
BUSINESS_WAS_CANCELED	O cadastro do cliente foi cancelado.

Contexto Invoice (Faturas)

Nome do evento (name)	Descrição
TRANSACTION_CREATED	Transação criada.
INVOICE_CLOSED	Fatura do cartão fechada.
INVOICE_PAYMENT_OPTION_CREATED	Opção de pagamento de boleto criada.
INVOICE_PAYMENT_PROCESSED	Pagamento proporcional da fatura do cartão processado.

Contexto Pocket

Nome do evento (name)	Descrição
POCKET_ACCOUNT_WAS_CREATED	Uma conta pocket foi criada.
POCKET_ACCOUNT_WAS_FULLY_CLOSED	Uma conta pocket foi totalmente encerrada.
POCKET_ACCOUNT_WAS_TECHNICALLY_CLOSED	Foi realizado o encerramento técnico de uma conta pocket.
POCKET_ACCOUNT_SAVING_WAS_COMPLETED	A conta pocket recebeu um depósito.
POCKET_ACCOUNT_REDEEM_WAS_COMPLETED	Um valor foi resgatado da conta pocket.
POCKET_ACCOUNT_SAVING_ERROR_OCCURRED	O depósito na conta pocket não pôde ser completado.
POCKET_ACCOUNT_REDEEM_ERROR_OCCURRED	O resgate de valor da conta pocket não pôde ser completado.
POCKET_ACCOUNT_USER_WAS_CHANGED	O usuário da conta pocket foi alterado.

Contexto Partner

Nome do evento (name)	Descrição
FEATURE_WAS_ENABLED	Uma feature foi habilitada.
FEATURE_WAS_DISABLED	Uma feature foi desabilitada.