Pular para o conteúdo principal
Aprenda a usar os webhooks do Localpayment para receber notificações em tempo real a cada evento de pagamento. Este guia ajuda você a validar assinaturas, processar dados de webhook e manter sua integração sincronizada. Usamos webhooks para notificar seu aplicativo sobre eventos que ocorrem em sua conta. Eles são especialmente úteis para atualizações assíncronas, como quando um pagamento é confirmado, um Payout é processado ou o status de uma assinatura é alterado.

Visão geral

Os webhooks fornecem notificações em tempo real sobre alterações no status das transações e outros eventos importantes em sua conta Localpayment. Em vez de consultar nossa API para obter atualizações de status, você pode configurar endpoints de webhook para receber notificações instantâneas quando os eventos ocorrerem.

Atualizações em tempo real

Receba notificações instantâneas quando o status de uma transação mudar

Múltiplos eventos

Suporte para Payins, Payouts, Virtual Accounts, assinaturas e muito mais

Entrega segura

A verificação da assinatura HMAC garante a autenticidade do webhook

Como funcionam os webhooks

  1. Ocorreu um evento: O status de uma transação foi alterado no sistema da Localpayment.
  2. Enviar Webhook: O Localpayment envia uma carga útil JSON para o seu endpoint de webhook.
  3. Verificação de assinatura: Seu endpoint verifica a solicitação usando o cabeçalho x-Signature.
  4. Retorno 200 OK: Seu endpoint retornou uma resposta 200 OK.
  5. Evento de Processo: Seu aplicativo lida com os dados do webhook de forma assíncrona.
O cabeçalho Content-Type nas requisições de webhook enviadas é text/plain; charset=utf-8, e não application/json. O corpo da requisição continua sendo um payload JSON válido. Faça o parse como JSON independentemente do valor do cabeçalho Content-Type.

Pré-requisitos

Antes de configurar os webhooks, certifique-se de ter:

Configuração da conta

Configuração adequada da conta para o país de destino e verificação da empresa.

Chave Secreta

Sua chave secreta de webhook do Business Portal Localpayment.

Configuração

Configuração do Business Portal

  1. Acesse Configurações → Clientes no seu Business Portal Localpayment.
  2. Selecione o cliente que deseja configurar.
  3. Clique na aba Notificações e escolha o tipo de webhook que deseja configurar.
  4. Clique no botão Adicionar e insira as seguintes informações:

Segurança e Autenticação

A Localpayment assina todas as solicitações de webhook com uma assinatura HMAC para verificar sua autenticidade.

Verificação de assinatura

Cada solicitação de webhook inclui um cabeçalho x-Signature. O valor é formatado como o nome do algoritmo seguido de um espaço e a assinatura HMAC-SHA256 codificada em hexadecimal:
Para verificar a assinatura, calcule o hash HMAC-SHA256 do corpo bruto da requisição usando sua chave secreta do webhook e compare-o com a parte do hash do cabeçalho — a parte após HMAC-SHA256 .
Remova o prefixo HMAC-SHA256 do valor do cabeçalho antes de comparar. Comparar a string completa do cabeçalho com o hash calculado sempre resultará em falha.

Exemplo de implementação


Cargas úteis de webhook

Todas as cargas úteis de webhook compartilham uma estrutura comum, com dados específicos do evento no objeto data. Esse formato consistente facilita o parsing e o tratamento de webhooks em diferentes tipos de evento.

Estrutura comum de webhook

Os seguintes campos estão sempre presentes em todos os payloads de webhook, independentemente do tipo de evento:
transactionType aparece duas vezes por design. O campo no nível raiz funciona como chave de roteamento para o seu handler de webhook. O campo é repetido dentro do objeto data para tornar cada payload autocontido — útil ao armazenar ou encaminhar eventos individualmente. Ambos os valores serão sempre idênticos.
Tipo de fxSource. O campo fxSource é sempre um float. Ele representa a taxa de câmbio usada no cálculo da tarifa ou do imposto. Quando nenhuma conversão cambial se aplica (transações na mesma moeda), o valor é 0 ou 0.0.

Eventos de Payin

Pagamentos com cartão (crédito/débito)

Approved
Chargeback
Completed
Refunded
Rejected

Conta Master para Transferências Bancárias

Assinaturas


Eventos de Payout


Eventos de Virtual Account

Criação de Virtual Account

Após a criação bem-sucedida de uma Virtual Account, o Localpayment enviará uma solicitação POST para o URL de retorno de chamada configurado. Essa notificação confirma que os detalhes da conta estão ativos e prontos para receber pagamentos.

Pagamento recebido (Payin)

Sempre que um cliente conclui um pagamento para uma Virtual Account, o Localpayment envia uma notificação webhook para o seu endpoint registrado. Todas as notificações de Payin seguem a mesma estrutura e contêm as mesmas informações, independentemente do momento ou do valor do pagamento. Isso inclui campos importantes como valor, moeda, status e referência da transação, permitindo que você automatize a conciliação e atualize os sistemas internos de acordo.

Eventos de Câmbio

Os campos a seguir são específicos para eventos de webhook de câmbio de moedas:
Completed

Eventos de Liquidação

Wire In

Completed

Wire Out

Completed

Wire Out (cripto)

Quando um Wire Out é pago em uma criptomoeda suportada (por exemplo, USDT ou USDC), o callback de conclusão também inclui um campo hash com o hash da transação na blockchain, para que você possa verificar o pagamento de forma independente em um explorador de blocos. Esse campo não está presente nos payloads de Wire Out em moeda fiduciária.
Completed (crypto)

Referência de campo

Compreender os campos detalhados na carga útil do webhook é essencial para a reconciliação e liquidação corretas.
Última modificação em 19 de novembro de 2026