Manual
Start typing to search…

Pagamento de Contas (Payments)

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

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. Neste caso, "Received" (recebido).
paymentType string Tipo de pagamento. Neste caso, "Bill" (conta).
account object Objeto que contém informações sobre a conta do pagador.
account.branch string Número da agência.
account.number string Número da conta.
account.bank object Objeto que contém informações sobre o 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 informações sobre o 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 informações sobre o 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 que contém informações sobre o recebedor do pagamento.
recipiente.document object Objeto que contém informações sobre o documento do recebedor do pagamento.
recipiente.document.type string Tipo do documento, que 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 informações sobre o documento do titular da conta.
document.value string Número do documento.
document.type string Tipo do documento, que 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. Neste caso, "Created" (criado).
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. Neste caso, "Confirmed" (confirmado).
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. Neste caso, "PaymentFailed" (falha no pagamento).
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. Neste caso, "Canceled" (cancelado).
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. Neste caso, "PaymentRefused" (pagamento recusado).
paymentType string Tipo de pagamento. Neste caso, "Bill" (conta).
account object Objeto que contém informações sobre a conta do pagador.
account.branch string Número da agência.
account.bank object Objeto que contém informações sobre o 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 informações sobre o 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 que contém informações sobre o recebedor do pagamento.
recipiente.document object Objeto que contém informações sobre o documento do recebedor do pagamento.
recipiente.document.type string Tipo do documento, que 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 12 days ago