Boleto
stable
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:
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:
![](https://files.readme.io/bc384c2-Fluxo_eventos.jpg)
Identificador (entityId
)
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
data
do eventoO 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
{
"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
data
do eventoO 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
{
"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
data
do eventoO 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
{
"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
data
do eventoO 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
{
"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 4 months ago