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

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
PaymentBILL_PAYMENT_WAS_RECEIVEDSolicitação de pagamento recebida.
PaymentBILL_PAYMENT_WAS_CREATED Pagamento criado.
PaymentBILL_PAYMENT_WAS_CONFIRMEDPagamento confirmado.
PaymentBILL_PAYMENT_HAS_FAILEDHouve falha no pagamento.
PaymentBILL_PAYMENT_WAS_CANCELLEDPagamento cancelado.
PaymentBILL_PAYMENT_WAS_REFUSEDPagamento 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:

NomeTipoDescrição
authenticationCodestringIdentificador da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "Received".
paymentTypestringTipo de pagamento, o qual neste caso sempre será "Bill".
accountobjectObjeto que contém os dados da conta do pagador.
account.branchstringNúmero da agência bancária.
account.numberstringNúmero da conta bancária.
account.bankobjectObjeto que contém os dados do banco ao qual a conta pertence.
account.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
account.bank.codestringCódigo do banco.
account.bank.namestringNome do banco.
createdAtstringData e hora em que a requisição foi recebida, no formato ISO 8601 - UTC.
digitablestringLinha digitável para pagamento.
amountobjectObjeto que contém os dados do valor pago.
amount.valuestringValor pago.
amount.currencystringCódigo da moeda com base na ISO-4217.
originalAmountobjectObjeto que contém os dados do valor original, sem desconto ou juros e/ou multas.
originalAmount.valuestringValor pago.
originalAmount.currencystringCódigo da moeda com base na ISO-4217.
assignorstringNome do cedente.
recipientobjectObjeto com os dados do recebedor do pagamento.
recipiente.documentobjectObjeto que contém os dados do documento do recebedor do pagamento.
recipiente.document.typestringTipo do documento, o qual pode ser: “undefined”, “CPF” ou “CNPJ”
chargesobjectObjeto 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.interestAmountCalculatedobjectObjeto que contém informações sobre os juros aplicados na transação.
charges.interestAmountCalculated.valuestringValor dos juros.
charges.interestAmountCalculated.currencystringCódigo da moeda com base na ISO-4217.
charges.fineAmountCalculatedobjectObjeto que contém informações sobre a multa aplicada na transação.
charges.fineAmountCalculated.valuestringValor da multa.
charges.fineAmountCalculated.currencystringCódigo da moeda com base na ISO-4217.
charges.discountAmountobjectObjeto que contém informações sobre o desconto aplicado na transação.
charges.discountAmount.valuestringValor do desconto.
charges.discountAmount.currencystringCódigo da moeda com base na ISO-4217.
settleDatestringData 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.
paymentDatestringData em que foi realizado o pagamento, no formato ISO 8601 - UTC.
typestringTipo de título a ser pago.
dueDatestringData de vencimento do título, no formato ISO 8601 - UTC.
transactionIdstringCódigo identificador da transação.
descriptionstringDescriçã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:

NomeTipoDescrição
documentobjectObjeto que contém os dados do documento do titular da conta.
document.valuestringNúmero do documento.
document.typestringTipo do documento, o qual pode ser "CPF" ou "CNPJ".
authenticationCodestringIdentificador da transação.
confirmationTransactionIdnumberCódigo de confirmação da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "Created".
updatedAtstringData 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:

NomeTipoDescrição
authenticationCodestringIdentificador da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "Confirmed".
confirmedAtstringData em que o pagamento foi confirmado, no formato ISO 8601 - UTC.
updatedAtstringData 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:

NomeTipoDescrição
authenticationCodestringIdentificador da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "PaymentFailed".
errorobjectObjeto que contém informações referentes à falha no pagamento.
error.codestringCódigo de erro.
error.messagestringMensagem de erro.
updatedAtstringData 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:

NomeTipoDescrição
authenticationCodestringIdentificador da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "Canceled".
reasonstringMotivo pelo qual ocorreu o cancelamento.
updatedAtstringData 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:

NomeTipoDescrição
authenticationCodestringIdentificador da transação.
paymentStatusstringSituação do pagamento, a qual neste caso será "PaymentRefused".
paymentTypestringTipo de pagamento, o qual neste caso sempre será "Bill".
accountobjectObjeto que contém os dados da conta do pagador.
account.branchstringNúmero da agência bancária.
account.bankobjectObjeto que contém os dados do banco ao qual a conta pertence.
account.bank.ispbstringISPB (Identificador de Sistema de Pagamentos Brasileiro) do banco.
account.bank.codestringCódigo do banco.
account.bank.namestringNome do banco.
updatedAtstringData da última atualização do status do pagamento, no formato ISO 8601 - UTC.
digitablestringLinha digitável para pagamento.
amountobjectObjeto que contém os dados do valor pago.
amount.valueobjectValor pago.
amount.currencyobjectCódigo da moeda com base na ISO-4217.
assignorstringNome do cedente.
recipientobjectObjeto com os dados do recebedor do pagamento.
recipiente.documentobjectObjeto que contém os dados do documento do recebedor do pagamento.
recipiente.document.typestringTipo do documento, o qual pode ser “undefined”, “CPF” ou “CNPJ”
settleDatestringData 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.
paymentDatestringData em que foi realizado o pagamento, no formato ISO 8601 - UTC.
typestringTipo de título a ser pago.
dueDatestringData 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"
}