Boleto

Os eventos de boletos disparam mensagens que comunicam ao destinatário sobre:

O recebimento de valores provenientes de pagamentos (cash-in);
A finalização do registro de um boleto;
O cancelamento do boleto pelo recebedor do pagamento;
O cancelamento motivado por decurso de prazo.

Pré-requisitos

Para receber esses eventos, o parceiro deverá:

Configurar previamente o recebedor de eventos do webhook.
Conhecer a estrutura básica dos eventos que acompanha o objeto data.

Informações sobre os eventos

Contexto e nome do evento

O contexto (context) e o nome do evento (name) poderão variar de acordo com a tabela a seguir:

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

Fluxo dos eventos

O fluxograma a seguir descreve a sequência em que os eventos ocorrem. Clique na imagem para ampliá-la:

Identificador (`entityId`)

O campo entityId é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.
No contexto de boleto, o entityId é o identificador da transação (authenticationCode).

Dados dos eventos

BOLETO_CASH_IN_WAS_RECEIVED

Este evento sinaliza que o valor foi recebido no core bancário Bankly.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação.
`amount`	`object`	Objeto que contém informações sobre o valor a ser transferido.
`amount.value`	`number`	Valor a ser transferido.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`recipient`	`object`	Objeto que contém informações sobre os dados do recebedor.
`recipient.document`	`object`	Objeto que contém informações sobre o documento do recebedor.
`recipient.document.value`	`string`	Número do documento.
`recipient.document.type`	`string`	Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.
`recipient.type`	`string`	Tipo de recebedor, o qual pode ser “Customer” ou “Business”.
`recipient.name`	`string`	Nome completo do recebedor.
`recipient.account`	`object`	Objeto que contém informações sobre a conta bancária do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`recipient.account.bank.isbp`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`recipient.account.bank.code`	`string`	Código do banco.
`recipient.account.bank.name`	`string`	Nome do banco.
`channel`	`object`	Objeto que contém informações sobre o canal de transferência.
`channel.name`	`string`	Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
`channel.ourNumber`	`string`	Identificador único contido no código de barras do boleto.
`createdAt`	`string`	Data em que o evento de registro ocorreu, no formato ISO 8601 - UTC.

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

{
      "entityId": "204b7865-549a-4086-9a42-958ee1389262",
      "companyKey": "FLORESTA_ED",
      "idempotencyKey": "56b5d77e-18ac-4a46-93f2-010586c3081c",
      "context": "Boleto",
      "name": "BOLETO_CASH_IN_WAS_RECEIVED",
      "timestamp": "2022-11-09T11:31:37.647434Z",
      "correlationId": "56b5d77e-18ac-4a46-93f2-010586c3081c",
      "data": {
         "authenticationCode": "204b7865-549a-4086-9a42-958ee1389262",
         "amount": {
            "value": 262.5,
            "currency": "BRL"
         },
         "recipient": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "type": "Customer",
            "name": "Nísia Floresta",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                  "ispb": "13140088",
                  "code": "332",
                  "name": "Acesso Soluções de Pagamento S.A."
               }
            }
         },
         "channel": {
            "name": "Boleto",
            "ourNumber": "46478921539"
         },
         "createdAt": "2022-11-09T11:31:37.5970838Z"
      },
      "version": "1"
   }

BOLETO_CASH_IN_WAS_CLEARED

Este evento sinaliza que o valor foi liberado na conta destino.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação.
`amount`	`object`	Objeto que contém informações sobre o valor a ser transferido.
`amount.value`	`number`	Valor a ser transferido.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`recipient`	`object`	Objeto que contém informações sobre os dados do recebedor.
`recipient.document`	`object`	Objeto que contém informações sobre o documento do recebedor.
`recipient.document.value`	`string`	Número do documento.
`recipient.document.type`	`string`	Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.
`recipient.type`	`string`	Tipo de recebedor, o qual pode ser “Customer” ou “Business”.
`recipient.name`	`string`	Nome completo do recebedor.
`recipient.account`	`object`	Objeto que contém informações sobre a conta bancária do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`recipient.account.bank.isbp`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`recipient.account.bank.code`	`string`	Código do banco.
`recipient.account.bank.name`	`string`	Nome do banco.
`channel`	`object`	Objeto que contém informações sobre o canal de transferência.
`channel.name`	`string`	Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
`channel.ourNumber`	`string`	Identificador único contido no código de barras do boleto.
`createdAt`	`string`	Data em que o evento de registro ocorreu, no formato ISO 8601 - UTC.

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

{
      "entityId": "204b7865-549a-4086-9a42-958ee1389262",
      "companyKey": "FLORESTA_ED",
      "idempotencyKey": "56b5d77e-18ac-4a46-93f2-010586c3081c",
      "context": "Boleto",
      "name": "BOLETO_CASH_IN_WAS_CLEARED",
      "timestamp": "2022-11-09T11:31:38.2669076Z",
      "correlationId": "56b5d77e-18ac-4a46-93f2-010586c3081cb",
      "data": {
         "authenticationCode": "204b7865-549a-4086-9a42-958ee1389262",
         "amount": {
            "value": 262.5,
            "currency": "BRL"
         },
         "recipient": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "type": "Customer",
            "name": "Nísia Floresta",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                  "ispb": "13140088",
                  "code": "332",
                  "name": "Acesso Soluções de Pagamento S.A."
               }
            }
         },
         "channel": {
            "name": "Boleto",
            "ourNumber": "46478921539"
         },
         "createdAt": "2022-11-09T11:31:34.9106453Z"
      }
   }

BOLETO_WAS_REGISTERED

Este evento sinaliza que o boleto está apto para pagamento.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação.
`barcode`	`string`	Número do código de barras do boleto.
`amount`	`object`	Objeto que contém informações sobre o valor a ser transferido.
`amount.value`	`number`	Valor a ser transferido.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`recipient`	`object`	Objeto que contém informações sobre os dados do recebedor.
`recipient.document`	`object`	Objeto que contém informações sobre o documento do recebedor.
`recipient.document.value`	`string`	Número do documento.
`recipient.document.type`	`string`	Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.
`recipient.type`	`string`	Tipo de recebedor, o qual pode ser “Customer” ou “Business”.
`recipient.name`	`string`	Nome completo do recebedor.
`recipient.account`	`object`	Objeto que contém informações sobre a conta bancária do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`recipient.account.bank.isbp`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`recipient.account.bank.code`	`string`	Código do banco.
`recipient.account.bank.name`	`string`	Nome do banco.
`channel`	`object`	Objeto que contém informações sobre o canal de transferência.
`channel.name`	`string`	Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
`channel.ourNumber`	`string`	Identificador único contido no código de barras do boleto.
`createdAt`	`string`	Data em que o evento de registro ocorreu, no formato ISO 8601 - UTC.

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

{
      "entityId": "a9f174c0-2a95-473c-935a-cc26fded2720",
      "companyKey": "ACESSO",
      "idempotencyKey": "3bd7ebbb-87f4-4210-8631-51853d6c6026",
      "context": "Boleto",
      "name": "BOLETO_WAS_REGISTERED",
      "timestamp": "2022-12-12T13:34:59.1917887Z",
      "correlationId": "00000000-0000-0000-0000-000000000000",
      "metadata": {
         "RequestedAt": 1670852099
      },
      "data": {
         "authenticationCode": "a9f174c0-2a95-473c-935a-cc26fded2720",
       	 "barcode": "33293940400000001000001113321409407500712060",
         "amount": {
            "value": 150,
            "currency": "BRL"
         },
         "recipient": {
            "document": {
               "value": "47742663023",
               "type": "CPF"
            },
            "type": "Customer",
            "name": "Nísia Floresta",
            "account": {
               "branch": "0001",
               "number": "15164",
               "bank": {
                  "ispb": "13140088",
                  "code": "332",
                  "name": "Acesso Soluções de Pagamento S.A."
               }
            }
         },
         "channel": {
            "name": "Boleto",
            "ourNumber": "43779993688"
         },
         "createdAt": "2022-12-12T13:34:56.1245582Z"
      },
      "version": "1.0"
   }

BOLETO_WAS_CANCELLED_BY_RECIPIENT

Este evento sinaliza que o boleto foi cancelado pelo recebedor do pagamento.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação.
`barcode`	`string`	Número do código de barras do boleto.
`amount`	`object`	Objeto que contém informações sobre o valor a ser transferido.
`amount.value`	`number`	Valor a ser transferido.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`recipient`	`object`	Objeto que contém informações sobre os dados do recebedor.
`recipient.document`	`object`	Objeto que contém informações sobre o documento do recebedor.
`recipient.document.value`	`string`	Número do documento.
`recipient.document.type`	`string`	Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.
`recipient.type`	`string`	Tipo de recebedor, o qual pode ser “Customer” ou “Business”.
`recipient.name`	`string`	Nome completo do recebedor.
`recipient.account`	`object`	Objeto que contém informações sobre a conta bancária do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`recipient.account.bank.isbp`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`recipient.account.bank.code`	`string`	Código do banco.
`recipient.account.bank.name`	`string`	Nome do banco.
`channel`	`object`	Objeto que contém informações sobre o canal de transferência.
`channel.name`	`string`	Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
`channel.ourNumber`	`string`	Identificador único contido no código de barras do boleto.
`createdAt`	`string`	Data em que o evento de cancelamento ocorreu, no formato ISO 8601 - UTC.

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

{  
    "entityId": "09e92c1f-2f05-45b1-a4ef-ebdbf9cc7914",  
    "companyKey": "SDB2_BANKLYDELIVERY",  
    "idempotencyKey": "c5e88040-864c-4e23-8ea7-5a21370fd7df",  
    "context": "Boleto",  
    "name": "BOLETO_WAS_CANCELLED_BY_RECIPIENT",  
    "timestamp": "2023-07-14T18:12:50.2685371Z",  
    "correlationId": "c6c956e6-e4af-4bb5-944c-63bce32ce28e",  
    "metadata": {  
        "RequestedAt": 1689358370  
    },  
    "data": {  
        "authenticationCode": "09e92c1f-2f05-45b1-a4ef-ebdbf9cc7914",  
        "barcode": "33291941100000001000001119443602764900754846",  
        "amount": {  
            "value": 1,  
            "currency": "BRL"  
        },  
        "recipient": {  
            "document": {  
                "value": "47742663023",  
                "type": "CPF"  
            },  
            "type": "Customer",  
            "name": "Nísia Floresta",  
            "account": {  
                "branch": "0001",  
                "number": "15164",  
                "bank": {  
                    "ispb": "13140088",  
                    "code": "332",  
                    "name": "Acesso Soluções de Pagamento S.A."  
                }  
            }  
        },  
        "channel": {  
            "name": "Boleto",  
            "ourNumber": "94436027649"  
        },  
        "createdAt": "2023-07-14T18:12:50.2685371Z"  
    },  
    "version": "1.0"  
  }

BOLETO_WAS_CANCELLED_BY_DEADLINE

Esse evento indica que um boleto foi cancelado por decurso de prazo. Ou seja, o boleto não foi pago até a data limite (closePayment) e não poderá mais ser pago.

Descrição do objeto `data` do evento

O objeto data traz detalhes específicos do contexto em que o evento ocorre. Neste caso, o objeto trará os campos de acordo com a tabela:

Nome	Tipo	Descrição
`authenticationCode`	`string`	Identificador da transação.
`barcode`	`string`	Número do código de barras do boleto.
`amount`	`object`	Objeto que contém informações sobre o valor a ser transferido.
`amount.value`	`number`	Valor a ser transferido.
`amount.currency`	`string`	Código da moeda com base na ISO-4217.
`recipient`	`object`	Objeto que contém informações sobre os dados do recebedor.
`recipient.document`	`object`	Objeto que contém informações sobre o documento do recebedor.
`recipient.document.value`	`string`	Número do documento.
`recipient.document.type`	`string`	Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.
`recipient.type`	`string`	Tipo de recebedor, o qual pode ser “Customer” ou “Business”.
`recipient.name`	`string`	Nome completo do recebedor.
`recipient.account`	`object`	Objeto que contém informações sobre a conta bancária do recebedor.
`recipient.account.branch`	`string`	Número da agência.
`recipient.account.number`	`string`	Número da conta.
`recipient.account.bank`	`object`	Objeto que contém informações sobre o banco ao qual a conta pertence.
`recipient.account.bank.isbp`	`string`	ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
`recipient.account.bank.code`	`string`	Código do banco.
`recipient.account.bank.name`	`string`	Nome do banco.
`channel`	`object`	Objeto que contém informações sobre o canal de transferência.
`channel.name`	`string`	Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
`channel.ourNumber`	`string`	Identificador único contido no código de barras do boleto.
`createdAt`	`string`	Data em que o evento de cancelamento ocorreu, no formato ISO 8601 - UTC.

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

{
        "entityId": "8ca006a5-c26e-4696-93e0-27af8c2de58c",
        "companyKey": "ACESSO",
        "idempotencyKey": "d802e46d-b2aa-4b79-8680-3bc8d3b45f27",
        "context": "Boleto",
        "name": "BOLETO_WAS_CANCELLED_BY_DEADLINE",
        "timestamp": "2023-08-04T13:35:07.6006987Z",
        "correlationId": "748353e2-edaf-4e28-b988-41ca2d7d8b09",
        "metadata": {
          "RequestedAt": 1691156107
        },
        "data": {
          "authenticationCode": "8ca006a5-c26e-4696-93e0-27af8c2de58c",
          "barcode": "33299942200000010000001112530843445200000060",
          "amount": {
            "value": 5000.0,
            "currency": "BRL"
          },
          "recipient": {
            "document": {
              "value": "47742663023",
              "type": "CPF"
            },
            "type": "Customer",
            "name": "Nísia Floresta",
            "account": {
              "branch": "0001",
              "number": "15164",
              "bank": {
                "ispb": "13140088",
                "code": "332",
                "name": "Acesso Soluções de Pagamento S.A."
              }
            }
          },
          "channel": {
            "name": "Boleto",
            "ourNumber": "74186453470"
          },
          "createdAt": "2023-08-04T13:35:07.6006647Z"
        },
        "version": "1.0"
      }

Pré-requisitos

Informações sobre os eventos

Contexto e nome do evento

Fluxo dos eventos

Identificador (entityId)

Dados dos eventos

BOLETO_CASH_IN_WAS_RECEIVED

Descrição do objeto data do evento

Payload do evento

BOLETO_CASH_IN_WAS_CLEARED

Descrição do objeto data do evento

Payload do evento

BOLETO_WAS_REGISTERED

Descrição do objeto data do evento

Payload do evento

BOLETO_WAS_CANCELLED_BY_RECIPIENT

Descrição do objeto data do evento

Payload do evento

BOLETO_WAS_CANCELLED_BY_DEADLINE

Descrição do objeto data do evento

Payload do evento

Identificador (`entityId`)

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento