Payments Webhooks (Brazil)

Um webhook é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico.

Este artigo é sobre webhooks para nossa solução de Iniciação de Pagamentos. Para informações sobre nossos webhooks de Agregação e Enriquecimento, confira este artigo

Configurar webhooks

Para configurar um novo webhook:

No seu painel do Belvo, vá para a seção de webhooks de pagamento.
Na aba Payments Webhooks, clique em +New webhook.
Preencha o formulário de New webhook com as informações necessárias.
- URL: a URL para receber as notificações do webhook.
- Authorization: um token bearer opcional para usar se sua URL estiver protegida.
Clique em Create webhook.

Tipos de webhook

Todos os eventos de webhook vêm com um payload principal (conforme descrito no exemplo de código abaixo).

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "The payment consent was not accepted in time.",
    "end_to_end_id": "E432158152024081610416f2b595b056",
  }
}

Parâmetro	Obrigatório	Tipo	Descrição	Exemplo
`webhook_id`	sim	string	O ID do webhook da Belvo.	`aadf41a1fc8e4f79a49f7f04027ac999`
`webhook_type`	sim	string	O recurso ao qual este webhook se refere.	`CHARGES`
`webhook_code`	sim	string	O evento que acionou o webhook.	`STATUS_UPDATE`
`object_id`	sim	string	O ID do objeto ao qual este webhook se refere.	`d2e40773-19f6-48d1-93c3-3590ec0c74df`
`external_id`	sim	string	O identificador único que você forneceu ao criar o objeto. Para cobranças e transações, este campo sempre retornará `null`.	`c3c51aaf-aaa3-400c-926d-87ab62e195fd`
`data`	sim	object	Um objeto contendo dados específicos sobre o evento. Os campos retornados neste objeto dependem do `webhook_type` e `webhook_code`.	Veja as linhas seguintes.
`data.status`	não	string	O status da cobrança ou intenção de pagamento.	`FAILED`
`data.failure_code`	não	string	No caso de a cobrança ou intenção de pagamento falhar, um código único para o erro.	`consent_expired`
`data.failure_message`	não	string	No caso de a cobrança ou intenção de pagamento falhar, uma descrição legível do erro.	`The payment consent was not accepted in time.`
`data.end_to_end_id`	não	string	O ID do pagamento no sistema de pagamentos do Brasil.	`E432158152024081610416f2b595b056`
`data.metadata`	não	object	Se você forneceu qualquer informação no objeto `metadata` ao criar seu pagamento, ela será incluída no corpo do webhook.	`{ "internal_reference_id": "GGq12345w2" }`

Para informações sobre os dados específicos de um determinado webhook, clique no tipo de webhook na tabela abaixo.

Tipo	Evento	Enviado sempre que...
CHARGES	`STATUS_UPDATE`	Há uma atualização no status de uma intenção de pagamento
PAYMENT_INTENTS	`STATUS_UPDATE`	Há uma atualização no status de uma intenção de pagamento.
TRANSACTIONS	`OBJECT_CREATED`	Há uma nova transação criada.

Endereços IP de saída do webhook

Você pode receber eventos de webhook dos seguintes endereços IP:

3.130.254.46
18.220.61.186
18.223.45.212

Recomendamos fortemente que você coloque esses endereços IP na lista de permissões para que possa receber eventos de webhook.

Melhor prática de resposta de webhook no lado do cliente

Recomendamos fortemente que, assim que você receber um webhook, responda à Belvo com um código de status 2XX dentro de cinco segundos para confirmar que você recebeu o webhook. Caso contrário, nossa API tentará novamente a solicitação.

Política de tentativas de webhook

Se o nosso sistema não receber um código de status 2XX, ele tentará automaticamente enviar a solicitação novamente. Este processo de tentativa ocorrerá até três vezes, com cada tentativa espaçada por 60 segundos. Por exemplo, se a primeira tentativa falhar, nosso sistema espera 60 segundos antes de tentar novamente e continuará esse padrão até que receba uma resposta bem-sucedida ou atinja o máximo de três tentativas.

slug: "ofpi-webhooks"

Cobranças

STATUS_UPDATE

Você receberá um evento de webhook sempre que o status de uma cobrança for atualizado para:

Evento	Enviado quando
`SCHEDULED`	A cobrança está 'pausada' até a data de pagamento agendada.
`SUCCEEDED`	A cobrança foi confirmada e processada pela rede de open finance.
`FAILED`	O usuário não forneceu consentimento para o pagamento, ou houve um erro geral na rede de open finance.
`CANCELED`	A cobrança agendada foi cancelada.

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CHARGES",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": null,
  "data": {
    "status": "SUCCEEDED", // O status da cobrança.
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": null,
    "failure_message": null,
    "end_to_end_id": "E432158152024081610416f2b595b056",
  },
}

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CHARGES",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": null,
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "O consentimento para o pagamento não foi aceito a tempo.",
    "end_to_end_id": "E432158152024081610416f2b595b056"
  }
}

Códigos e mensagens de falha

Abaixo está uma lista de failure_codes e failure_messages que você pode receber em um webhook de Cobranças quando uma cobrança falha:

Código	Mensagem	Quando pode ocorrer
`AMOUNT_OVER_LIMIT`	O valor do pagamento ou o número de pagamentos excede os limites estabelecidos pela instituição.	Atualização de Status
`AUTHORIZATION_EXPIRED`	O tempo de autorização expirou.	Atualização de Status
`CONSENT_PENDING_AUTHORIZATION`	Consentimento pendente de autorização de múltiplos níveis (status 'PARTIALLY_ACCEPTED').	Atualização de Status
`HOLDER_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do titular da conta.	Atualização de Status
`ICP_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do ICP (Infraestrutura de Chaves Públicas).	Atualização de Status
`INSUFFICIENT_FUNDS`	A conta não possui fundos suficientes para realizar o pagamento.	Atualização de Status
`INVALID_CHARGE`	A cobrança é inválida ou incorreta.	Atualização de Status
`INVALID_PAYMENT_DETAIL`	Os detalhes do pagamento fornecidos são inválidos.	Atualização de Status
`NOT_INFORMED`	Nenhuma razão de erro foi fornecida pela instituição.	Na Criação
`PAYMENT_CONSENT_MISMATCH`	Os detalhes do pagamento não correspondem ao consentimento fornecido.	Na Criação
`PAYMENT_REFUSED_BY_HOLDER`	O pagamento foi recusado pelo titular da conta.	Na Criação, Atualização de Status
`PAYMENT_REFUSED_BY_SPI`	O pagamento foi recusado pelo SPI (Sistema de Pagamentos Instantâneos).	Atualização de Status
`PAYMENT_SCHEDULING_FAILURE`	Houve uma falha no agendamento do pagamento.	Atualização de Status
`RECEIVING_PSP_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do PSP (Provedor de Serviços de Pagamento) recebedor.	Atualização de Status
`SAME_ORIGIN_DESTINATION_ACCOUNTS`	As contas de origem e destino são as mesmas.	Atualização de Status
`SPI_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do SPI.	Atualização de Status
`SPI_REJECTED_PAYMENT`	Pagamento rejeitado no Sistema de Pagamentos Instantâneos (SPI).	Atualização de Status
`USER_REJECTED`	O usuário rejeitou a autorização do consentimento.	Atualização de Status

Clientes

OBJECT_CREATED

Sempre que um novo cliente for criado pelo aplicativo Belvo (ou seja, quando o cliente for criado de forma assíncrona e não como resultado de uma chamada POST direta), você receberá o seguinte webhook:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "CUSTOMERS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": null
}

Assim que você receber a notificação, poderá obter detalhes sobre o cliente fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/payments/br/customers/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

id é o object_id do cliente (que você recebe no evento do webhook).

Inscrições

STATUS_UPDATE

Você receberá um evento de webhook sempre que o status de uma inscrição for atualizado para:

Evento	Enviado quando
`PENDING`	A inscrição está aguardando o envio dos detalhes biométricos.
`SUCCEEDED`	A inscrição foi aceita pela instituição.
`FAILED`	A inscrição foi rejeitada pela instituição.

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "06a51b80-708d-49c9-8620-7b0fd2fbc548",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "PENDING",
    "metadata": null,
    "details": { "status": "AWAITING_ENROLLMENT" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "SUCCEEDED",
    "metadata": null,
    "details": { "status": "AUTHORIZED" }
  }
}

{
  "webhook_id": "9f91116b-bfe1-45f2-8ae3-aa604161c4aa",
  "webhook_type": "ENROLLMENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "e64de9d0-0045-49ad-b1ee-779a9c269ab3",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": null,
    "details": { "status": "REJECTED" }
  }
}

Intenções de pagamento

STATUS_UPDATE

Você receberá um evento de webhook sempre que o status de uma intenção de pagamento for atualizado para:

Evento	Enviado quando
`REQUIRES_PAYMENT_METHOD`	Detalhes adicionais são necessários para completar o fluxo da intenção de pagamento.
`REQUIRES_ACTION`	Você enviou através de `confirm=true` no fluxo da intenção de pagamento e a Belvo agora inicia o fluxo de pagamento na rede de open finance.
`PROCESSING`	O pagamento está sendo processado na rede de open finance.
`SCHEDULED`	O pagamento está 'pausado' até a data de pagamento agendada.
`CANCELED`	A intenção de pagamento agendada foi cancelada.
`SUCCEEDED`	O pagamento foi confirmado e processado pela rede de open finance.
`FAILED`	O pagamento foi rejeitado pelo usuário, o usuário não forneceu consentimento para o pagamento, ou houve um erro geral na rede de open finance.

`STATUS_UPDATE` webhook ao usar links de pagamento

Você também receberá webhooks STATUS_UPDATE ao usar links de pagamento. Por favor, veja o artigo Processo de pagamento do Widget de nossos pagamentos de entrada OFPI para informações detalhadas sobre quando cada evento de webhook é enviado.

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "SUCCEEDED",
    "end_to_end_id": "E432158152024081610416f2b595b056",
    "metadata": {"internal_reference_id": "GGq12345w2"}
  },
}

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "O consentimento para o pagamento não foi aceito a tempo.",
    "end_to_end_id": "E432158152024081610416f2b595b056",
  }
}

Assim que você receber a notificação, poderá obter detalhes sobre a intenção de pagamento fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/payments/br/payment-intents/{id}' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

id é o object_id da intenção de pagamento (que você recebe no evento de webhook).

Códigos e mensagens de falha

Abaixo está uma lista de failure_codes e failure_messages que você pode receber em um webhook de Payment Intents quando uma cobrança falha:

Código	Mensagem	Quando pode ocorrer
`AMOUNT_OVER_LIMIT`	O valor do pagamento ou o número de pagamentos excede os limites estabelecidos pela instituição.	Atualização de Status
`AUTHORIZATION_EXPIRED`	O tempo de autorização expirou.	Atualização de Status
`CONSENT_PENDING_AUTHORIZATION`	Consentimento pendente de autorização de múltiplos níveis (status 'PARTIALLY_ACCEPTED').	Atualização de Status
`HOLDER_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do titular da conta.	Atualização de Status
`ICP_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do ICP (Infraestrutura de Chaves Públicas).	Atualização de Status
`INSUFFICIENT_FUNDS`	A conta não possui fundos suficientes para realizar o pagamento.	Atualização de Status
`INVALID_CHARGE`	A cobrança é inválida ou incorreta.	Atualização de Status
`INVALID_PAYMENT_DETAIL`	Os detalhes do pagamento fornecidos são inválidos.	Atualização de Status
`NOT_INFORMED`	Nenhuma razão de erro foi fornecida pela instituição.	Na Criação
`PAYMENT_CONSENT_MISMATCH`	Os detalhes do pagamento não correspondem ao consentimento fornecido.	Na Criação
`PAYMENT_REFUSED_BY_HOLDER`	O pagamento foi recusado pelo titular da conta.	Na Criação, Atualização de Status
`PAYMENT_REFUSED_BY_SPI`	O pagamento foi recusado pelo SPI (Sistema de Pagamentos Instantâneos).	Atualização de Status
`PAYMENT_SCHEDULING_FAILURE`	Houve uma falha no agendamento do pagamento.	Atualização de Status
`RECEIVING_PSP_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do PSP (Provedor de Serviços de Pagamento) receptor.	Atualização de Status
`SAME_ORIGIN_DESTINATION_ACCOUNTS`	As contas de origem e destino são as mesmas.	Atualização de Status
`SPI_INFRASTRUCTURE_FAILURE`	Houve uma falha na infraestrutura do SPI.	Atualização de Status
`SPI_REJECTED_PAYMENT`	Pagamento rejeitado no Sistema de Pagamentos Instantâneos (SPI).	Atualização de Status
`USER_REJECTED`	O usuário rejeitou a autorização do consentimento.	Atualização de Status

Transações

OBJECT_CREATED

Sempre que uma nova transação for criada, você receberá o seguinte webhook:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "data": {
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "end_to_end_id": "E432158152024081610416f2b595b056",
  },
}

Assim que você receber a notificação, poderá obter detalhes sobre a transação fazendo a seguinte solicitação:

curl --request GET 'https://api.belvo.com/payments/br/transactions/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD]

Onde:

id é o object_id da transação (que você recebe no evento do webhook).

Payments Webhooks (Brazil)

Configurar webhooks

Tipos de webhook

Endereços IP de saída do webhook

Melhor prática de resposta de webhook no lado do cliente

Política de tentativas de webhook

Cobranças

STATUS_UPDATE

Códigos e mensagens de falha

Clientes

OBJECT_CREATED

Inscrições

STATUS_UPDATE

Intenções de pagamento

STATUS_UPDATE

Códigos e mensagens de falha

Transações

OBJECT_CREATED

Quão útil foi esta página?