Manual
Start typing to search…

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.

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:

contextnameDescrição
BoletoBOLETO_CASH_IN_WAS_RECEIVED

O valor foi recebido no core bancário.

BoletoBOLETO_CASH_IN_WAS_CLEARED

O valor foi liberado na conta destino.

BoletoBOLETO_WAS_REGISTERED

O boleto está apto para pagamento.

BoletoBOLETO_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:

NomeTipoDescrição
authenticationCodestring

Identificador da transação.

barcodestring

Número do código de barras do boleto.

digitablestring

Linha digitável para pagamento do boleto.

amountobject

Objeto que contém informações sobre o valor a ser transferido.

amount.valuenumber

Valor a ser transferido.

amount.currencystring

Código da moeda com base na ISO-4217.

recipientobject

Objeto que contém informações sobre os dados do beneficiário final.

recipient.documentobject

Objeto que contém informações sobre o documento do beneficiário final.

recipient.document.valuestring

Número do documento.

recipient.document.typestring

Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.

recipient.typestring

Tipo de beneficiário final, o qual pode ser “Customer” ou “Business”.

recipient.namestring

Nome completo do beneficiário final.

recipient.accountobject

Objeto que contém informações sobre a conta bancária do beneficiário final.

recipient.account.branchstring

Número da agência.

recipient.account.numberstring

Número da conta.

recipient.account.bankobject

Objeto que contém informações sobre o banco ao qual a conta pertence.

recipient.account.bank.isbpstring

ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.

recipient.account.bank.codestring

Código do banco.

recipient.account.bank.namestring

Nome do banco.

channelobject

Objeto que contém informações sobre o canal de transferência.

channel.namestring

Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.

channel.ourNumberstring

Identificador único contido no código de barras do boleto.

createdAtstring

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",
           "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:

NomeTipoDescrição
authenticationCodestring

Identificador da transação.

barcodestring

Número do código de barras do boleto.

digitablestring

Linha digitável para pagamento do boleto.

amountobject

Objeto que contém informações sobre o valor a ser transferido.

amount.valuenumber

Valor a ser transferido.

amount.currencystring

Código da moeda com base na ISO-4217.

recipientobject

Objeto que contém informações sobre os dados do beneficiário final.

recipient.documentobject

Objeto que contém informações sobre o documento do beneficiário final.

recipient.document.valuestring

Número do documento.

recipient.document.typestring

Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.

recipient.typestring

Tipo de beneficiário final, o qual pode ser “Customer” ou “Business”.

recipient.namestring

Nome completo do beneficiário final.

recipient.accountobject

Objeto que contém informações sobre a conta bancária do beneficiário final.

recipient.account.branchstring

Número da agência.

recipient.account.numberstring

Número da conta.

recipient.account.bankobject

Objeto que contém informações sobre o banco ao qual a conta pertence.

recipient.account.bank.isbpstring

ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.

recipient.account.bank.codestring

Código do banco.

recipient.account.bank.namestring

Nome do banco.

channelobject

Objeto que contém informações sobre o canal de transferência.

channel.namestring

Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.

channel.ourNumberstring

Identificador único contido no código de barras do boleto.

createdAtstring

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",
           "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:

NomeTipoDescrição
authenticationCodestring

Identificador da transação.

barcodestring

Número do código de barras do boleto.

digitablestring

Linha digitável para pagamento do boleto.

amountobject

Objeto que contém informações sobre o valor a ser transferido.

amount.valuenumber

Valor a ser transferido.

amount.currencystring

Código da moeda com base na ISO-4217.

recipientobject

Objeto que contém informações sobre os dados do beneficiário final.

recipient.documentobject

Objeto que contém informações sobre o documento do beneficiário final.

recipient.document.valuestring

Número do documento.

recipient.document.typestring

Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.

recipient.typestring

Tipo de beneficiário final, o qual pode ser “Customer” ou “Business”.

recipient.namestring

Nome completo do beneficiário final.

recipient.accountobject

Objeto que contém informações sobre a conta bancária do beneficiário final.

recipient.account.branchstring

Número da agência.

recipient.account.numberstring

Número da conta.

recipient.account.bankobject

Objeto que contém informações sobre o banco ao qual a conta pertence.

recipient.account.bank.isbpstring

ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.

recipient.account.bank.codestring

Código do banco.

recipient.account.bank.namestring

Nome do banco.

channelobject

Objeto que contém informações sobre o canal de transferência.

channel.namestring

Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.

channel.ourNumberstring

Identificador único contido no código de barras do boleto.

createdAtstring

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": "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:

NomeTipoDescrição
authenticationCodestring

Identificador da transação.

barcodestring

Número do código de barras do boleto.

digitablestring

Linha digitável para pagamento do boleto.

amountobject

Objeto que contém informações sobre o valor a ser transferido.

amount.valuenumber

Valor a ser transferido.

amount.currencystring

Código da moeda com base na ISO-4217.

recipientobject

Objeto que contém informações sobre os dados do beneficiário final.

recipient.documentobject

Objeto que contém informações sobre o documento do beneficiário final.

recipient.document.valuestring

Número do documento.

recipient.document.typestring

Tipo do documento, o qual pode ser “CPF” ou “CNPJ”.

recipient.typestring

Tipo de beneficiário final, o qual pode ser “Customer” ou “Business”.

recipient.namestring

Nome completo do beneficiário final.

recipient.accountobject

Objeto que contém informações sobre a conta bancária do beneficiário final.

recipient.account.branchstring

Número da agência.

recipient.account.numberstring

Número da conta.

recipient.account.bankobject

Objeto que contém informações sobre o banco ao qual a conta pertence.

recipient.account.bank.isbpstring

ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.

recipient.account.bank.codestring

Código do banco.

recipient.account.bank.namestring

Nome do banco.

channelobject

Objeto que contém informações sobre o canal de transferência.

channel.namestring

Nome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.

channel.ourNumberstring

Identificador único contido no código de barras do boleto.

reasonstring

Motivo do cancelamento do boleto, que pode ser "CancelledByRecipient" (cancelado pelo emissor) ou "CancelledByDeadLine" (cancelado por decurso de prazo).

createdAtstring

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",
          "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 about 13 hours ago