Saltar al contenido principal
Recibe notificaciones instantáneas mediante webhook para cada pago de Cuenta Virtual, y actualiza tus sistemas y confirma los créditos automáticamente. Una vez que crees una cuenta virtual y la asocies a un cliente o factura específicos dentro de tus sistemas internos, Localpayment enviará automáticamente una notificación webhook a tu servidor cada vez que se reciba un pago correctamente en esa cuenta. Importante: Una cuenta virtual funciona como destino de pago exclusivo. Si bien tú gestionas tu atribución interna, el número de cuenta puede recibir fondos de cualquier pagador. La notificación de pago incluirá los detalles del pagador real, lo que te permitirá conciliar el pago con tu registro interno de clientes. Estas notificaciones en tiempo real te permiten confirmar automáticamente los créditos, actualizar los saldos y conciliar los pagos sin necesidad de verificación manual.

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

  1. El pagador envía una transferencia al número de cuenta virtual generado previamente por tu sistema.
  2. Una vez que Localpayment acredite y valide los fondos, se enviará una notificación de Payin al endpoint de webhook configurado.
  3. Tu sistema debe confirmar la notificación con una respuesta 200 OK.
  4. A continuación, puedes actualizar tus registros internos para marcar la Cuenta Virtual como pagada o el pedido correspondiente como completado.

Localpayment garantiza la entrega mediante reintentos con retroceso exponencial si tu servidor no responde con HTTP 200.

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 objeto tracking del webhook para coincidencia directa.

Importante
  • Disponibilidad: El objeto tracking solo está disponible en los webhooks, no en los informes de transacciones ni en la API.
  • Para México (SPID), el externalId corresponde a la clave de seguimiento del Banco de México (Clave de Rastreo), lo que lo convierte en el campo autorizado para la conciliación.

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 formato XXXX-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".
No confíes en 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 pagoConsideraciones sobre los webhooks
Costa Rica (SINPE)
  • El campo tracking.concept contiene la descripción ingresada por el pagador en el momento de la transferencia. Este valor puede ser truncado por el banco originador, razón por la cual puedes ver guiones bajos al final (por ejemplo, "Steph_test_____").
Colombia (Bre-B)
  • paymentMethod.code siempre es "2006" para pagos de la cuenta virtual Bre-B.
  • payer.bank.account.type siempre es "BREB" — confirma que el pagador envió los fondos a través de la red Bre-B.
  • beneficiary.bank.account.type siempre es "KEY" — la llave Bre-B receptora asignada a tu cuenta virtual.
  • Bre-B liquida en tiempo real: el único estado de pago es "200" COMPLETED. No existen estados intermedios.
  • tracking.id y tracking.reference contienen el ID de transacción de la red Bre-B; utilízalos como referencia autorizada para la conciliación.
  • tracking.concept puede contener una descripción ingresada por el pagador, pero a menudo lleva una cadena generada por el sistema (por ejemplo, "Transfer via BRE-B"). No lo trates como texto libre ingresado por el pagador garantizado.
México (SPID)
  • Las transferencias SPID están disponibles exclusivamente para los pagadores de la empresa.
  • El campo externalId corresponde a la clave de seguimiento (Clave de Rastreo) asignada por el Banco de México.
  • Usar externalId como referencia autorizada para la reconciliación.
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.
  • 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:
  1. Verifica la firma de la solicitud.
  2. Validar el internalId o externalId para garantizar la idempotencia; nunca proceses la misma notificación dos veces.
  3. Actualiza tu sistema para marcar la factura, la billetera o el pedido correspondiente como pagado.
  4. Devolver HTTP 200 OK para acusar recibo.

Acuse de recibo de la notificación

Localpayment considera que el webhook se ha entregado correctamente solo cuando tu servidor responde con:
Si no se recibe ninguna confirmación, Localpayment vuelve a intentar enviar la notificación varias veces con intervalos cada vez mayores.
Última modificación el 10 de noviembre de 2026