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.
`timestamp`	`string`	Data e a hora em que o evento ocorreu, no formato ISO 8601 - 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.0",
      "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
Authorization	Agrupa todos os eventos relacionados à autorização e à confirmação de transações com o cartão, bem como aqueles relativos à necessidade da criação de um desafio de autenticação para o prosseguimento de uma compra realizada pelo cliente.
Boleto	Agrupa todos os eventos relacionados a boletos, como emissão, cancelamento, compensação etc.
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.
Contas (Account)	Agrupa todos os eventos relacionados à acordos legais, abertura e encerramento de contas (por solicitação do cliente, parceiro ou Bankly), assim como eventos referentes a bloqueio/desbloqueio judicial.
Crédito (Credit)	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.
Envio de documentos de Onboarding (Document)	Agrupa todos os eventos relacionados ao recebimento e o processamento de imagens para Onboarding.
Faturas (Invoice)	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.
Pagamento de contas (Payment)	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.
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.
Pessoa física (Customer)	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa física.
Pessoa jurídica (Business) - MEI, EI, EIRELI ou SLU e LTDA, S.A. e TS	Agrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa jurídica.
Pix e DICT	Agrupa todos os eventos relacionados a cash-in e cash-out, refunds (devoluções), QR Codes Pix, DICT, pedidos de portabilidade e reivindicação de chaves Pix.
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.
TED	Agrupa todos os eventos relacionados a cash-in, cash-out e refunds (devoluções) via TED.

Estrutura

🚧Importante

Exemplos

Contextos

🚧
Importante