Pagamento de contas (Payment)
stable
Os eventos de pagamentos de contas disparam mensagens sempre que há atualizações sobre a criação, o recebimento, a confirmação, a devolução e o cancelamento do pagamento, assim como se houve falha na transação.
Para mais informações sobre quando estes eventos são disparados e sobre o seu conteúdo, consulte as páginas:
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 |
---|---|---|
Payment | BILL_PAYMENT_WAS_RECEIVED | Solicitação de pagamento recebida. |
Payment | BILL_PAYMENT_WAS_CREATED | Pagamento criado. |
Payment | BILL_PAYMENT_WAS_CONFIRMED | Pagamento confirmado. |
Payment | BILL_PAYMENT_HAS_FAILED | Houve falha no pagamento. |
Payment | BILL_PAYMENT_WAS_CANCELLED | Pagamento cancelado. |
Payment | BILL_PAYMENT_WAS_REFUSED | Pagamento recusado devido a problemas identificados após a sua confirmação. O valor foi estornado ao pagador. |
Fluxo dos eventos
O fluxograma a seguir descreve a sequência em que os eventos ocorrem. Clique na imagem para ampliá-la:
Identificador (entityId
)
entityId
)O campo entityId
é o identificador da entidade emissora do evento e seu valor depende do contexto de sua emissão.
Neste caso, o entityId
é o código identificador da transação (AuthenticationCode
).
Dados dos eventos
BILL_PAYMENT_WAS_RECEIVED
Esse evento sinaliza que uma solicitação de pagamento de conta foi recebida.
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. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "Received". |
paymentType | string | Tipo de pagamento, o qual neste caso sempre será "Bill". |
account | object | Objeto que contém os dados da conta do pagador. |
account.branch | string | Número da agência bancária. |
account.number | string | Número da conta bancária. |
account.bank | object | Objeto que contém os dados do banco ao qual a conta pertence. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
createdAt | string | Data e hora em que a requisição foi recebida, no formato ISO 8601 - UTC. |
digitable | string | Linha digitável para pagamento. |
amount | object | Objeto que contém os dados do valor pago. |
amount.value | string | Valor pago. |
amount.currency | string | Código da moeda com base na ISO-4217. |
originalAmount | object | Objeto que contém os dados do valor original, sem desconto ou juros e/ou multas. |
originalAmount.value | string | Valor pago. |
originalAmount.currency | string | Código da moeda com base na ISO-4217. |
assignor | string | Nome do cedente. |
recipient | object | Objeto com os dados do recebedor do pagamento. |
recipiente.document | object | Objeto que contém os dados do documento do recebedor do pagamento. |
recipiente.document.type | string | Tipo do documento, o qual pode ser: “undefined”, “CPF” ou “CNPJ” |
charges | object | Objeto que contém informações sobre os encargos aplicados na transação. Caso nenhum encargo seja aplicado, este objeto, assim como os referentes à multa, juros e desconto também serão retornados, porém com valor zerado. |
charges.interestAmountCalculated | object | Objeto que contém informações sobre os juros aplicados na transação. |
charges.interestAmountCalculated.value | string | Valor dos juros. |
charges.interestAmountCalculated.currency | string | Código da moeda com base na ISO-4217. |
charges.fineAmountCalculated | object | Objeto que contém informações sobre a multa aplicada na transação. |
charges.fineAmountCalculated.value | string | Valor da multa. |
charges.fineAmountCalculated.currency | string | Código da moeda com base na ISO-4217. |
charges.discountAmount | object | Objeto que contém informações sobre o desconto aplicado na transação. |
charges.discountAmount.value | string | Valor do desconto. |
charges.discountAmount.currency | string | Código da moeda com base na ISO-4217. |
settleDate | string | Data em que o pagamento será liquidado, no formato ISO 8601 - UTC. Caso a data de vencimento coincida com feriados ou finais de semana, esse campo informará a data do próximo dia útil. |
paymentDate | string | Data em que foi realizado o pagamento, no formato ISO 8601 - UTC. |
type | string | Tipo de título a ser pago. |
dueDate | string | Data de vencimento do título, no formato ISO 8601 - UTC. |
transactionId | string | Código identificador da transação. |
description | string | Descrição da conta a ser paga. |
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": "affedb25-9002-4a35-a02b-c298adc3895f",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_WAS_RECEIVED",
"timestamp": "2022-04-25T12:27:25.7038327+00:00",
"correlationId": "ae7eaab1-a367-4687-989b-5578b90f0a72",
"metadata": null,
"data": {
"authenticationCode": "affedb25-9002-4a35-a02b-c298adc3895f",
"paymentStatus": "Received",
"paymentType": "Bill",
"account": {
"branch": "0001",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções De Pagamento S.A."
},
"number": "15164"
},
"createdAt": "2022-04-25T12:27:23.8078938Z",
"digitable": "856300000036128800692021204300202205422400081630",
"amount": {
"value": 312.88,
"currency": "BRL"
},
"originalAmount": {
"value": 312.88,
"currency": "BRL"
},
"assignor": "Boleto dos livros",
"recipient": {
"document": {
"type": "Undefined"
}
},
"charges": {
"interestAmountCalculated": {
"value": 0,
"currency": "BRL"
},
"fineAmountCalculated": {
"value": 0,
"currency": "BRL"
},
"discountAmount": {
"value": 0,
"currency": "BRL"
}
},
"settleDate": "2022-04-25T00:00:00Z",
"paymentDate": "2022-04-25T12:27:23.8078995Z",
"type": "Concessionaire",
"dueDate": "2022-04-25T00:00:00Z",
"transactionId": 1000978470,
"description": "DESCRIPTION"
}
}
BILL_PAYMENT_WAS_CREATED
Esse evento sinaliza que o pagamento de uma conta foi criado.
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 |
---|---|---|
document | object | Objeto que contém os dados do documento do titular da conta. |
document.value | string | Número do documento. |
document.type | string | Tipo do documento, o qual pode ser "CPF" ou "CNPJ". |
authenticationCode | string | Identificador da transação. |
confirmationTransactionId | number | Código de confirmação da transação. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "Created". |
updatedAt | string | Data da última atualização do status do pagamento, 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": "31951261-79b2-40e4-849c-a326ca0baf3c",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_WAS_CREATED",
"timestamp": "2022-04-25T12:28:03.4363558+00:00",
"correlationId": "661204fb-6d0e-4600-83fa-a85b42c2c49c",
"metadata": null,
"data": {
"document": {
"value": "34183937000161",
"type": "CNPJ"
},
"authenticationCode": "31951261-79b2-40e4-849c-a326ca0baf3c",
"confirmationTransactionId": 1000981186,
"paymentStatus": "Created",
"updatedAt": "2022-04-25T12:28:03.4360996Z"
}
}
BILL_PAYMENT_WAS_CONFIRMED
Esse evento sinaliza que o pagamento de uma conta foi confirmado.
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. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "Confirmed". |
confirmedAt | string | Data em que o pagamento foi confirmado, no formato ISO 8601 - UTC. |
updatedAt | string | Data da última atualização do status do pagamento, 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": "ffac45d7-0644-4f9f-887f-97d2f179a51a",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_WAS_CONFIRMED",
"timestamp": "2022-04-25T12:26:05.3835097+00:00",
"correlationId": "d096bdae-4fdb-457a-9854-dbe6e3ae7a20",
"metadata": null,
"data": {
"authenticationCode": "ffac45d7-0644-4f9f-887f-97d2f179a51a",
"paymentStatus": "Confirmed",
"confirmedAt": "2022-04-25T12:26:05.3834893Z",
"updatedAt": "2022-04-25T12:26:05.3834893Z"
}
}
BILL_PAYMENT_HAS_FAILED
Esse evento sinaliza que houve falha no pagamento da conta.
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. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "PaymentFailed". |
error | object | Objeto que contém informações referentes à falha no pagamento. |
error.code | string | Código de erro. |
error.message | string | Mensagem de erro. |
updatedAt | string | Data da última atualização do status do pagamento, 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": "553d341e-786e-47b8-9854-b53175d2585d",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_HAS_FAILED",
"timestamp": "2022-04-19T21:13:25.5742107+00:00",
"correlationId": "59466911-0ca3-4651-a6c3-23e9029bb508",
"data": {
"authenticationCode": "553d341e-786e-47b8-9854-b53175d2585d",
"paymentStatus": "PaymentFailed",
"error": {
"code": "000",
"message": "ESPERANDO_CONFIRMACAO_CLIENTE"
},
"updatedAt": "2022-04-19T21:13:25.5191272Z"
},
"context": "Payment"
}
BILL_PAYMENT_WAS_CANCELLED
Esse evento sinaliza que o pagamento de uma conta foi cancelado, após detecção de falha no 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. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "Canceled". |
reason | string | Motivo pelo qual ocorreu o cancelamento. |
updatedAt | string | Data da última atualização do status do pagamento, 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": "553d341e-786e-47b8-9854-b53175d2585d",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_WAS_CANCELLED",
"timestamp": "2022-04-19T21:13:25.5744646+00:00",
"correlationId": "59466911-0ca3-4651-a6c3-23e9029bb508",
"data": {
"authenticationCode": "553d341e-786e-47b8-9854-b53175d2585d",
"paymentStatus": "Canceled",
"reason": "ESPERANDO_CONFIRMACAO_CLIENTE",
"updatedAt": "2022-04-19T21:13:25.553292Z"
},
"context": "Payment"
}
BILL_PAYMENT_WAS_REFUSED
Esse evento sinaliza que o pagamento de uma conta foi recusado, devido a problemas identificados após a sua confirmação. O valor foi estornado ao pagador.
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. |
paymentStatus | string | Situação do pagamento, a qual neste caso será "PaymentRefused". |
paymentType | string | Tipo de pagamento, o qual neste caso sempre será "Bill". |
account | object | Objeto que contém os dados da conta do pagador. |
account.branch | string | Número da agência bancária. |
account.bank | object | Objeto que contém os dados do banco ao qual a conta pertence. |
account.bank.ispb | string | ISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco. |
account.bank.code | string | Código do banco. |
account.bank.name | string | Nome do banco. |
updatedAt | string | Data da última atualização do status do pagamento, no formato ISO 8601 - UTC. |
digitable | string | Linha digitável para pagamento. |
amount | object | Objeto que contém os dados do valor pago. |
amount.value | object | Valor pago. |
amount.currency | object | Código da moeda com base na ISO-4217. |
assignor | string | Nome do cedente. |
recipient | object | Objeto com os dados do recebedor do pagamento. |
recipiente.document | object | Objeto que contém os dados do documento do recebedor do pagamento. |
recipiente.document.type | string | Tipo do documento, o qual pode ser “undefined”, “CPF” ou “CNPJ” |
settleDate | string | Data em que o pagamento será liquidado, no formato ISO 8601 - UTC. Caso a data de vencimento coincida com feriados ou finais de semana, esse campo informará a data do próximo dia útil. |
paymentDate | string | Data em que foi realizado o pagamento, no formato ISO 8601 - UTC. |
type | string | Tipo de título a ser pago. |
dueDate | string | Data de vencimento do título, 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": "387e74fe-6610-4531-99d1-e74fe7fc3441",
"companyKey": "COMPANY_KEY",
"name": "BILL_PAYMENT_WAS_REFUSED",
"timestamp": "2023-07-22T01:00:04.8873198+00:00",
"correlationId": "4f512dbe-340a-40d7-88c1-39218e5b0a39",
"data": {
"authenticationCode": "387e74fe-6610-4531-99d1-e74fe7fc3441",
"paymentStatus": "PaymentRefused",
"paymentType": "Bill",
"account": {
"branch": "0001",
"bank": {
"ispb": "13140088",
"code": "332",
"name": "Acesso Soluções de Pagamento S.A."
},
"number": "32132131"
},
"updatedAt": "2023-07-22T01:00:04.7746687Z",
"digitable": "846100000013099900820897992726720500000000001992",
"amount": {
"value": 109.99,
"currency": "BRL"
},
"assignor": "VIVO",
"recipient": {
"document": {
"type": "CPF"
}
},
"settleDate": "2023-07-19T00:00:00Z",
"paymentDate": "2023-07-19T15:05:56.735111Z",
"type": "Concessionaire",
"dueDate": "2023-07-19T00:00:00Z"
},
"context": "Payment",
"version": "1.0"
}
Updated 6 months ago