Saltar al contenido principal
Aprende a usar los webhooks de Localpayment para recibir notificaciones en tiempo real de cada pago. Esta guía te ayudará a validar firmas, procesar datos de webhook y mantener tu integración sincronizada. Utilizamos webhooks para notificar a tu aplicación sobre los eventos que ocurren en tu cuenta. Son especialmente útiles para actualizaciones asíncronas, como cuando se confirma un pago, se procesa un desembolso o cambia el estado de una suscripción.

Descripción general

Los webhooks proporcionan notificaciones en tiempo real sobre cambios en el estado de las transacciones y otros eventos importantes en tu cuenta de Localpayment. En lugar de consultar nuestra API periódicamente para obtener actualizaciones de estado, puedes configurar los endpoints de los webhooks para recibir notificaciones instantáneas cuando se produzcan eventos.

Actualizaciones en tiempo real

Recibe notificaciones instantáneas cuando cambie el estado de la transacción

Múltiples eventos

Compatibilidad con payins, payouts, cuentas virtuales, suscripciones y más

Entrega segura

La verificación de la firma HMAC garantiza la autenticidad del webhook

Cómo funcionan los webhooks

  1. Evento ocurrido: El estado de una transacción cambia en el sistema de Localpayment.
  2. Enviar webhook: Localpayment envía una carga útil JSON a tu endpoint de webhook.
  3. Verificación de firma: Tu endpoint verifica la solicitud mediante el encabezado x-Signature.
  4. Devuelve 200 OK: Tu endpoint devuelve una respuesta 200 OK.
  5. Procesar el evento: Tu aplicación gestiona los datos del webhook de forma asíncrona.
El encabezado Content-Type de las solicitudes de webhook salientes es text/plain; charset=utf-8, no application/json. El cuerpo de la solicitud sigue siendo una carga útil JSON válida. Analízalo como JSON independientemente del valor del encabezado Content-Type.

Requisitos previos

Antes de configurar los webhooks, asegúrate de tener lo siguiente:

Configuración de la cuenta

Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

Llave secreta

Tu clave secreta de webhook del portal comercial de Localpayment.

Configuración

Configuración del Business Portal

  1. En tu portal comercial de Localpayment, ve a Configuraciones → Clientes.
  2. Selecciona el cliente que deseas configurar.
  3. Haz clic en la pestaña Notificaciones y elige el tipo de webhook que deseas configurar.
  4. Haz clic en el botón Agregar e introduce la siguiente información:

Seguridad y autenticación

Localpayment firma todas las solicitudes de webhook con una firma HMAC para verificar su autenticidad.

Verificación de firma

Cada solicitud de webhook incluye un encabezado x-Signature. El valor tiene el formato del nombre del algoritmo seguido de un espacio y la firma HMAC-SHA256 codificada en hexadecimal:
Para verificar la firma, calcula el hash HMAC-SHA256 del cuerpo de la solicitud sin procesar utilizando tu clave secreta de webhook y luego compáralo con la parte del hash del encabezado, la parte posterior a HMAC-SHA256 .
Elimina el prefijo HMAC-SHA256 del valor del encabezado antes de compararlo. Comparar la cadena completa del encabezado con el hash calculado siempre dará error.

Ejemplo de implementación


Cargas útiles de webhook

Todas las cargas útiles de webhook comparten una estructura común, con datos específicos del evento en el objeto data. Este formato coherente facilita el análisis y la gestión de los webhooks en los distintos tipos de evento.

Estructura común de webhook

Los siguientes campos siempre están presentes en la carga útil de cada webhook, independientemente del tipo de evento:
transactionType aparece dos veces por diseño. El campo de nivel raíz actúa como clave de enrutamiento para el manejador de tus webhooks. El campo se repite dentro del objeto data para que cada carga útil sea autónoma, lo cual resulta útil al almacenar o reenviar eventos de forma individual. Ambos valores siempre serán idénticos.
Tipo de fxSource. El campo fxSource es siempre un float. Representa el tipo de cambio utilizado para el cálculo de la comisión o el impuesto. Cuando no se aplica ninguna conversión de divisas (transacciones en la misma divisa), el valor es 0 o 0.0.

Eventos de Payin

Pagos con tarjeta (crédito/débito)

Approved
Chargeback
Completed
Refunded
Rejected

Cuenta maestra de transferencia bancaria

Suscripciones


Eventos de Payout


Eventos de cuentas virtuales

Creación de cuenta virtual

Tras crear correctamente una cuenta virtual, Localpayment enviará una solicitud POST a la URL de devolución de llamada que hayas configurado. Esta notificación confirma que los datos de la cuenta están activos y listos para recibir pagos.

Pago recibido (payin)

Cada vez que un cliente realiza un pago a una cuenta virtual, Localpayment envía una notificación webhook a tu endpoint registrado. Todas las notificaciones de payin siguen la misma estructura y contienen la misma información, independientemente del momento o el importe del pago. Estas incluyen campos clave como el importe, la moneda, el estado y la referencia de la transacción, lo que te permite automatizar la conciliación y actualizar los sistemas internos según corresponda.

Eventos de cambio de divisas

Los siguientes campos son específicos de los eventos webhook de cambio de divisas:
Completed

Eventos de liquidación

Wire In

Completed

Wire Out

Completed

Wire Out (cripto)

Cuando un Wire Out se paga en una criptomoneda compatible (por ejemplo, USDT o USDC), el callback de completado también incluye un campo hash con el hash de la transacción blockchain, para que puedas verificar el pago de forma independiente en un explorador de bloques. Este campo no está presente en las cargas útiles de Wire Out en moneda fiat.
Completed (crypto)

Referencia de campo

Comprender los campos detallados en la carga útil del webhook es esencial para una correcta conciliación y liquidación.
Última modificación el 19 de noviembre de 2026