Antes de comenzar
Asegúrate de tener:- Se ha creado correctamente una cuenta virtual a través del endpoint Crear cuenta virtual.
- Un endpoint de notificación (URL de webhook) configurado en tu cuenta de comerciante.
- La capacidad de recibir solicitudes HTTPS POST desde los servidores de Localpayment.
- Lógica en tu sistema backend para validar y analizar de forma segura las cargas útiles de los webhooks.
Cómo funciona
- El pagador envía una transferencia al número de cuenta virtual generado previamente por tu sistema.
- Una vez que Localpayment acredite y valide los fondos, se enviará una notificación de Payin al endpoint de webhook configurado.
- Tu sistema debe confirmar la notificación con una respuesta 200 OK.
- A continuación, puedes actualizar tus registros internos para marcar la Cuenta Virtual como pagada o el pedido correspondiente como completado.
Ejemplo de notificación (carga útil del webhook)
A continuación se muestra un ejemplo de la carga útil de un pago exitoso acreditado a una cuenta virtual:Campos de webhook para coincidencia
La notificación del webhook contiene campos específicos que sirven como identificadores. Utiliza la tabla a continuación para cotejar el pago recibido con tus registros internos.Uso de referencias de pago
Los pagadores pueden agregar una referencia (por ejemplo, un número de pedido) a su transferencia. Estos datos aparecen en el objetotracking del webhook para coincidencia directa.
Ejemplo del objeto tracking
Identificadores clave en la notificación
La notificación incluye varios campos de referencia y seguimiento generados por diferentes partes. Comprender el origen y la fiabilidad de cada uno te ayudará a desarrollar una estrategia de conciliación fiable.referenceCode
Generado por Localpayment. Siempre sigue el formatoXXXX-XXXX-XXXX — tres bloques alfanuméricos de cuatro caracteres — en todos los países y plataformas de pago, lo que confirma que la notificación se originó en Localpayment.
referenceCode es una referencia de Localpayment legible por humanos, no una clave de idempotencia. Para la deduplicación y la idempotencia, utiliza internalId o externalId.
tracking.id
Generado por la plataforma de pago o el banco del pagador, no por Localpayment. El formato varía según el país:
No trates
tracking.id como único universal en todos los medios de pago. Úsalo como identificador principal del medio de pago para Colombia Bre-B; para otros países, trátalo como referencia complementaria.
tracking.reference
También generado por la plataforma de pago o el banco. Su contenido y disponibilidad varían:
- Argentina, Chile, Colombia: refleja
tracking.id. - México (SPEI/TEF): una referencia bancaria más corta que el pagador ingresa al momento de la transferencia.
- Perú: puede estar vacío o contener
"NO REF".
tracking.reference como identificador garantizado o único.
tracking.concept
Diseñado para contener la descripción del pago. En la práctica, este campo suele contener cadenas generadas por el sistema o marcadores de posición en lugar de texto libre del pagador:
No usar
tracking.concept como un campo clave o asumir que contiene texto libre ingresado por el pagador. Trátalo únicamente como contexto complementario.
Específico del país
Al usar cuentas virtuales, es importante tener en cuenta detalles específicos de cada país. Estos pueden afectar el procesamiento de las notificaciones de pago y la conciliación de las transacciones. A continuación, se presenta un resumen de las diferencias conocidas en ciertos mercados:| País / Método de pago | Consideraciones sobre los webhooks |
|---|---|
| Costa Rica (SINPE) |
|
| Colombia (Bre-B) |
|
| México (SPID) |
|
| Perú |
|
Instituciones financieras sin disponibilidad del nombre completo del pagador
- Perú: Algunas instituciones financieras peruanas no proporcionan el nombre completo del pagador en los detalles de la transacción. Debido a que esta información no está disponible en los datos de liquidación que envían estas entidades, es posible que no puedas identificar correctamente al pagador.
Lista de instituciones financieras
Lista de instituciones financieras
- 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
Gestión de la notificación
Tu servidor debe procesar cada notificación de la siguiente manera:- Verifica la firma de la solicitud.
- Validar el
internalIdoexternalIdpara garantizar la idempotencia; nunca proceses la misma notificación dos veces. - Actualiza tu sistema para marcar la factura, la billetera o el pedido correspondiente como pagado.
- Devolver
HTTP 200 OKpara acusar recibo.

