Visão geral

stable

Estrutura

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

NomeTipoDescrição
entityIdstringIdentificador 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.
companyKeystringChave que identifica o parceiro dentro do Bankly.
idempotencyKeystringValor retornado para evitar eventos duplicados (em formato UUID).
contextstringContexto em que o evento foi criado. Os possíveis contextos estão listados mais adiante nesta documentação.
namestringNome descritivo que identifica a operação realizada.
timestampstringData e a hora em que o evento ocorreu, no formato ISO 8601 - UTC.
correlationIdstringIdentificador que correlaciona todo o fluxo das operações.
versionstringVersão do evento.
metadataobjectInformaçõ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.
dataobjectEntidade 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

NomeDescrição
AuthorizationAgrupa 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.
BoletoAgrupa 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.
PartnerAgrupa 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 TSAgrupa todos os eventos relacionados a Onboarding e Offboarding de pessoa jurídica.
Pix e DICTAgrupa 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.
PocketAgrupa 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.
TEDAgrupa todos os eventos relacionados a cash-in, cash-out e refunds (devoluções) via TED.