Pagamento de contas (Payment)

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`)

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

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.
`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

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
`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

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.
`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

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.
`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

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.
`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

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.
`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"
}

Pré-requisitos

Informações sobre os eventos

Contexto e nome do evento

Fluxo dos eventos

Identificador (entityId)

Dados dos eventos

BILL_PAYMENT_WAS_RECEIVED

Descrição do objeto data do evento

Payload do evento

BILL_PAYMENT_WAS_CREATED

Descrição do objeto data do evento

Payload do evento

BILL_PAYMENT_WAS_CONFIRMED

Descrição do objeto data do evento

Payload do evento

BILL_PAYMENT_HAS_FAILED

Descrição do objeto data do evento

Payload do evento

BILL_PAYMENT_WAS_CANCELLED

Descrição do objeto data do evento

Payload do evento

BILL_PAYMENT_WAS_REFUSED

Descrição do objeto data do evento

Payload do evento

Identificador (`entityId`)

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento

Descrição do objeto `data` do evento