Pular para o conteúdo principal
Receba notificações instantâneas via webhook para cada pagamento da sua Conta Virtual e atualize seus sistemas e confirme os créditos automaticamente. Depois de criar uma conta virtual e associá-la a um cliente ou fatura específica em seus sistemas internos, o Localpayment envia automaticamente uma notificação via webhook para o seu servidor sempre que um pagamento for recebido com sucesso nessa conta. Importante: Uma conta virtual funciona como um destino de pagamento dedicado. Embora você gerencie a atribuição interna, o número da conta em si pode receber fundos de qualquer pagador. A notificação de pagamento conterá detalhes do pagador real, permitindo que você concilie o pagamento com seu mapeamento interno de clientes. Essas notificações em tempo real permitem que você confirme créditos, atualize saldos e concilie pagamentos automaticamente, sem verificação manual.

Antes de começar

Certifique-se de ter:
  • Conta virtual criada com sucesso através do endpoint Criar conta virtual.
  • Um endpoint de notificação (URL do webhook) configurado em sua conta de comerciante.
  • A capacidade de receber solicitações HTTPS POST dos servidores da Localpayment.
  • Lógica no seu backend para validar e analisar payloads de webhook com segurança.

Como funciona

  1. O pagador envia uma transferência para o número da Conta Virtual previamente gerado pelo seu sistema.
  2. Assim que os fundos forem creditados e validados pelo Localpayment, uma notificação de pagamento será enviada para o endpoint webhook configurado.
  3. Seu sistema deve reconhecer a notificação com uma resposta 200 OK.
  4. Em seguida, você poderá atualizar seus registros internos para marcar a Conta Virtual como paga ou o pedido correspondente como concluído.

O Localpayment garante a entrega por meio de novas tentativas com recuo exponencial caso seu servidor não responda com HTTP 200.

Exemplo de notificação (carga útil do webhook)

Segue abaixo um exemplo de carga útil para um pagamento bem-sucedido creditado em uma Conta Virtual:

Campos de webhook para correspondência

A notificação do webhook contém campos específicos que servem como identificadores. Use a tabela abaixo para associar o pagamento recebido aos seus registros internos.

Utilizando Referências de Pagamento

Os pagadores podem adicionar uma referência (por exemplo, um número de pedido) à sua transferência. Esses dados aparecem no objeto tracking do webhook para correspondência direta.

Importante
  • Disponibilidade: O objeto tracking está disponível apenas em webhooks, não em relatórios de transações ou na API.
  • Para o México (SPID), o externalId corresponde à chave de rastreamento do Banco de México (Clave de Rastreo), tornando-a o campo oficial para reconciliação.

Exemplo de objeto de rastreamento


Identificadores-chave na notificação

A notificação inclui diversos campos de referência e rastreamento gerados por diferentes partes. Compreender a origem e a confiabilidade de cada um deles ajuda a construir uma estratégia de reconciliação confiável.

referenceCode

Gerado pelo Localpayment. Segue sempre o formato XXXX-XXXX-XXXX — três blocos alfanuméricos de quatro caracteres — em todos os países e trilhos, o que confirma que a notificação se originou da Localpayment. referenceCode é uma referência Localpayment legível por humanos, não uma chave de idempotência. Para desduplicação e idempotência, use internalId ou externalId.

tracking.id

Gerado pela plataforma de pagamentos ou pelo banco do pagador, não pela Localpayment. O formato varia conforme o país: Não trate tracking.id como sendo universalmente único em todos os trilhos. Use-o como o principal identificador junto aos trilhos para a Colômbia Bre-B; para outros países, considere-o como uma referência complementar.

tracking.reference

Também gerado pelo trilho ou pelo banco. Seu conteúdo e disponibilidade variam:
  • Argentina, Chile, Colômbia: espelha tracking.id.
  • México (SPEI/TEF): uma referência bancária mais curta que o pagador insere no momento da transferência.
  • Peru: pode estar vazio ou conter "NO REF".
Não confie em tracking.reference como um identificador garantido ou único.

tracking.concept

Este campo destina-se a conter a descrição do pagamento. Na prática, frequentemente contém sequências de caracteres geradas pelo sistema ou marcadores de posição, em vez de texto livre do pagador: Não use tracking.concept como campo-chave nem presuma que ele contenha texto livre inserido pelo pagador. Trate-o apenas como contexto suplementar.

Específico para cada país

Ao usar Contas Virtuais, existem detalhes importantes específicos de cada país que você deve considerar. Esses detalhes podem afetar a forma como as notificações de pagamento são processadas e como você concilia as transações. Abaixo, segue um resumo das diferenças conhecidas em alguns mercados:
País / Método de pagamentoConsiderações sobre Webhooks
Costa Rica (SINPE)
  • O campo tracking.concept contém a descrição inserida pelo pagador no momento da transferência. Esse valor pode ser truncado pelo banco de origem, e é por isso que você pode ver sublinhados no final (por exemplo, "Steph_test_____").
Colômbia (Bre-B)
  • paymentMethod.code é sempre "2006" para pagamentos da conta virtual Bre-B.
  • payer.bank.account.type é sempre "BREB" — confirma que o pagador enviou fundos através da rede Bre-B.
  • beneficiary.bank.account.type é sempre "KEY" — a chave Bre-B receptora atribuída à sua Conta Virtual.
  • A Bre-B liquida os pagamentos em tempo real: o único status de pagamento é "200" COMPLETED. Não existem estados intermediários.
  • tracking.id e tracking.reference contêm o ID da transação da rede Bre-B — use-os como referência oficial para a reconciliação.
  • tracking.concept pode conter uma descrição inserida pelo pagador, mas geralmente contém uma sequência gerada pelo sistema (por exemplo, "Transfer via BRE-B"). Não o trate como texto livre garantidamente inserido pelo pagador.
México (SPID)
  • As transferências SPID estão disponíveis exclusivamente para empresas pagadoras.
  • O campo externalId corresponde à chave de rastreamento (Clave de Rastreo) atribuída pelo Banco de México.
  • Usar externalId como referência autorizada para a reconciliação.
Peru

Instituições financeiras sem disponibilidade do nome completo do pagador

  • Peru: Algumas instituições financeiras peruanas não fornecem o nome completo do pagador nos detalhes da transação. Como essa informação não está disponível nos dados de liquidação enviados por essas entidades, você pode não conseguir identificar corretamente o pagador.
  • 007 – CITIBANK DEL PERU S.A.
  • 056 – BANCO SANTANDER PERU S.A.
  • 805 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO SULLANA
  • 813 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO TACNA

Lidando com a notificação

Seu servidor deve processar cada notificação da seguinte forma:
  1. Verifique a assinatura da solicitação.
  2. Valide o internalId ou externalId para garantir a idempotência; nunca processe a mesma notificação duas vezes.
  3. Atualize seu sistema para marcar a fatura, carteira ou pedido correspondente como pago.
  4. Retorne HTTP 200 OK para confirmar o recebimento.

Confirmação do recebimento da notificação

O Localpayment considera que o webhook foi entregue com sucesso somente quando o seu servidor responde com:
Caso não seja recebida nenhuma confirmação, o Localpayment tenta reenviar a notificação várias vezes, com intervalos cada vez maiores.
Última modificação em 10 de novembro de 2026