Guides

Boleto

Suggest Edits

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.

Pré-requisitos

Para receber esses eventos, o parceiro deverá:

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 O boleto foi cancelado pelo beneficiário final ou 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.
barcode string Número do código de barras do boleto.
digitable string Linha digitável para pagamento 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 beneficiário final.
recipient.document object Objeto que contém informações sobre o documento do beneficiário final.
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 beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.name string Nome completo do beneficiário final.
recipient.account object Objeto que contém informações sobre a conta bancária do beneficiário final.
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
JSON
{
        "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",
           "barcode": "65597940700000001000001115801398869900725986",
           "digitable": "65590001151446968518579001874704188970000002000",
           "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.0"
     }

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.
barcode string Número do código de barras do boleto.
digitable string Linha digitável para pagamento 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 beneficiário final.
recipient.document object Objeto que contém informações sobre o documento do beneficiário final.
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 beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.name string Nome completo do beneficiário final.
recipient.account object Objeto que contém informações sobre a conta bancária do beneficiário final.
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
JSON
{
        "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",
           "barcode": "65597940700000001000001115801398869900725986",
           "digitable": "65590001151446968518579001874704188970000002000",
           "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"
        },
        "version": "1.0"
     }

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.
digitable string Linha digitável para pagamento 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 beneficiário final.
recipient.document object Objeto que contém informações sobre o documento do beneficiário final.
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 beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.name string Nome completo do beneficiário final.
recipient.account object Objeto que contém informações sobre a conta bancária do beneficiário final.
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
JSON
{
        "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": "65597940700000001000001115801398869900725986",
           "digitable": "65590001151446968518579001874704188970000002000",
           "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

Esse evento indica que um boleto foi cancelado pelo beneficiário final ou por decurso de prazo. Em caso de cancelamento por decurso de prazo, 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.
digitable string Linha digitável para pagamento 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 beneficiário final.
recipient.document object Objeto que contém informações sobre o documento do beneficiário final.
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 beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.name string Nome completo do beneficiário final.
recipient.account object Objeto que contém informações sobre a conta bancária do beneficiário final.
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.
reason string Motivo do cancelamento do boleto, que pode ser "CancelledByRecipient" (cancelado pelo emissor) ou "CancelledByDeadLine" (cancelado por decurso de prazo).
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
JSON
{
          "entityId": "8ca006a5-c26e-4696-93e0-27af8c2de58c",
          "companyKey": "ACESSO",
          "idempotencyKey": "d802e46d-b2aa-4b79-8680-3bc8d3b45f27",
          "context": "Boleto",
          "name": "BOLETO_WAS_CANCELLED",
          "timestamp": "2023-08-04T13:35:07.6006987Z",
          "correlationId": "748353e2-edaf-4e28-b988-41ca2d7d8b09",
          "metadata": {
            "RequestedAt": 1691156107
          },
          "data": {
            "authenticationCode": "8ca006a5-c26e-4696-93e0-27af8c2de58c",
            "barcode": "65597940700000001000001115801398869900725986",
            "digitable": "65590001151446968518579001874704188970000002000",
            "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"
            },
            "reason": "CancelledByRecipient",
            "createdAt": "2023-08-04T13:35:07.6006647Z"
          },
          "version": "1.0"
        }

Updated 5 months ago