InstitucionalBlogService DeskStatus Page

Boleto

stable

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:

contextnameDescrição
BoletoBOLETO_CASH_IN_WAS_RECEIVEDO valor foi recebido no core bancário Bankly.
BoletoBOLETO_CASH_IN_WAS_CLEAREDO valor foi liberado na conta destino.
BoletoBOLETO_WAS_REGISTEREDO boleto está apto para pagamento.
BoletoBOLETO_WAS_CANCELLEDO 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
authenticationCodestringIdentificador da transação.
barcodestringNúmero do código de barras do boleto.
digitablestringLinha digitável para pagamento do boleto.
amountobjectObjeto que contém informações sobre o valor a ser transferido.
amount.valuenumberValor a ser transferido.
amount.currencystringCódigo da moeda com base na ISO-4217.
recipientobjectObjeto que contém informações sobre os dados do beneficiário final.
recipient.documentobjectObjeto que contém informações sobre o documento do beneficiário final.
recipient.document.valuestringNúmero do documento.
recipient.document.typestringTipo do documento, o qual pode ser “CPF” ou “CNPJ”.
recipient.typestringTipo de beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.namestringNome completo do beneficiário final.
recipient.accountobjectObjeto que contém informações sobre a conta bancária do beneficiário final.
recipient.account.branchstringNúmero da agência.
recipient.account.numberstringNúmero da conta.
recipient.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
recipient.account.bank.isbpstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
recipient.account.bank.codestringCódigo do banco.
recipient.account.bank.namestringNome do banco.
channelobjectObjeto que contém informações sobre o canal de transferência.
channel.namestringNome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
channel.ourNumberstringIdentificador único contido no código de barras do boleto.
createdAtstringData 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
authenticationCodestringIdentificador da transação.
barcodestringNúmero do código de barras do boleto.
digitablestringLinha digitável para pagamento do boleto.
amountobjectObjeto que contém informações sobre o valor a ser transferido.
amount.valuenumberValor a ser transferido.
amount.currencystringCódigo da moeda com base na ISO-4217.
recipientobjectObjeto que contém informações sobre os dados do beneficiário final.
recipient.documentobjectObjeto que contém informações sobre o documento do beneficiário final.
recipient.document.valuestringNúmero do documento.
recipient.document.typestringTipo do documento, o qual pode ser “CPF” ou “CNPJ”.
recipient.typestringTipo de beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.namestringNome completo do beneficiário final.
recipient.accountobjectObjeto que contém informações sobre a conta bancária do beneficiário final.
recipient.account.branchstringNúmero da agência.
recipient.account.numberstringNúmero da conta.
recipient.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
recipient.account.bank.isbpstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
recipient.account.bank.codestringCódigo do banco.
recipient.account.bank.namestringNome do banco.
channelobjectObjeto que contém informações sobre o canal de transferência.
channel.namestringNome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
channel.ourNumberstringIdentificador único contido no código de barras do boleto.
createdAtstringData 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
authenticationCodestringIdentificador da transação.
barcodestringNúmero do código de barras do boleto.
digitablestringLinha digitável para pagamento do boleto.
amountobjectObjeto que contém informações sobre o valor a ser transferido.
amount.valuenumberValor a ser transferido.
amount.currencystringCódigo da moeda com base na ISO-4217.
recipientobjectObjeto que contém informações sobre os dados do beneficiário final.
recipient.documentobjectObjeto que contém informações sobre o documento do beneficiário final.
recipient.document.valuestringNúmero do documento.
recipient.document.typestringTipo do documento, o qual pode ser “CPF” ou “CNPJ”.
recipient.typestringTipo de beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.namestringNome completo do beneficiário final.
recipient.accountobjectObjeto que contém informações sobre a conta bancária do beneficiário final.
recipient.account.branchstringNúmero da agência.
recipient.account.numberstringNúmero da conta.
recipient.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
recipient.account.bank.isbpstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
recipient.account.bank.codestringCódigo do banco.
recipient.account.bank.namestringNome do banco.
channelobjectObjeto que contém informações sobre o canal de transferência.
channel.namestringNome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
channel.ourNumberstringIdentificador único contido no código de barras do boleto.
createdAtstringData 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
authenticationCodestringIdentificador da transação.
barcodestringNúmero do código de barras do boleto.
digitablestringLinha digitável para pagamento do boleto.
amountobjectObjeto que contém informações sobre o valor a ser transferido.
amount.valuenumberValor a ser transferido.
amount.currencystringCódigo da moeda com base na ISO-4217.
recipientobjectObjeto que contém informações sobre os dados do beneficiário final.
recipient.documentobjectObjeto que contém informações sobre o documento do beneficiário final.
recipient.document.valuestringNúmero do documento.
recipient.document.typestringTipo do documento, o qual pode ser “CPF” ou “CNPJ”.
recipient.typestringTipo de beneficiário final, o qual pode ser “Customer” ou “Business”.
recipient.namestringNome completo do beneficiário final.
recipient.accountobjectObjeto que contém informações sobre a conta bancária do beneficiário final.
recipient.account.branchstringNúmero da agência.
recipient.account.numberstringNúmero da conta.
recipient.account.bankobjectObjeto que contém informações sobre o banco ao qual a conta pertence.
recipient.account.bank.isbpstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
recipient.account.bank.codestringCódigo do banco.
recipient.account.bank.namestringNome do banco.
channelobjectObjeto que contém informações sobre o canal de transferência.
channel.namestringNome do tipo de canal de transferência bancária, o qual sempre será “Boleto”.
channel.ourNumberstringIdentificador único contido no código de barras do boleto.
reasonstringMotivo do cancelamento do boleto, que pode ser "CancelledByRecipient" (cancelado pelo emissor) ou "CancelledByDeadLine" (cancelado por decurso de prazo).
createdAtstringData 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 2 months ago