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
- O pagador envia uma transferência para o número da Conta Virtual previamente gerado pelo seu sistema.
- Assim que os fundos forem creditados e validados pelo Localpayment, uma notificação de pagamento será enviada para o endpoint webhook configurado.
- Seu sistema deve reconhecer a notificação com uma resposta 200 OK.
- Em seguida, você poderá atualizar seus registros internos para marcar a Conta Virtual como paga ou o pedido correspondente como concluído.
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 objetotracking do webhook para correspondência direta.
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 formatoXXXX-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".
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 pagamento | Considerações sobre Webhooks |
|---|---|
| Costa Rica (SINPE) |
|
| Colômbia (Bre-B) |
|
| México (SPID) |
|
| 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.
Lista de Instituições Financeiras
Lista de Instituições Financeiras
- 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:- Verifique a assinatura da solicitação.
- Valide o
internalIdouexternalIdpara garantir a idempotência; nunca processe a mesma notificação duas vezes. - Atualize seu sistema para marcar a fatura, carteira ou pedido correspondente como pago.
- Retorne
HTTP 200 OKpara confirmar o recebimento.

