Loyalty
Crea y gestiona programas de lealtad para tus clientes.
Introducción
Loyalty es el módulo que te permite crear y gestionar programas de puntos y cashback para tus clientes, sin necesidad de desarrollar ni mantener la infraestructura por tu cuenta.
- Define las reglas y edítalas cuando quieras.
- Sin necesidad de conocimiento técnico. Todo desde el Dashboard 24/7.
- Tus clientes siempre pueden consultar su saldo actualizado.
- Recibe reportes diarios y mensuales con toda la actividad del programa.
- Todo integrado al ciclo transaccional, sin fricción.
Funcionamiento
El servicio de Loyalty se integra automáticamente con el ciclo de vida de las transacciones. Cuando se crea un usuario o tarjeta, damos de alta al miembro en el programa de loyalty, sin que sea necesaria ninguna acción adicional de tu parte.
- Se aprueba una transacción: evaluamos las campañas activas, generamos los puntos o cashback correspondientes y te notificamos vía webhook que están pendientes.
- Se presenta la transacción: confirmamos los puntos o cashback y los acreditamos en la cuenta de tu cliente. Recibes la información con el saldo actualizado vía webhook.
- Si la transacción se reversa o vence el período para presentarla: los puntos o cashback en estado pendiente se cancelan automáticamente y no se acreditan.
Refunds de transacciones capturadas
Cuando llega un refund sobre una transacción con puntos o cashback ya confirmados, restamos los puntos o cashback correspondientes al monto devuelto y emitimos un webhook loyalty-confirm reflejando la resta aplicada sobre el balance del member.
El tratamiento varía según el tipo de refund:
- Refund total: se restan todos los puntos o cashback confirmados de la transacción original.
- Refund parcial: se aplica un ajuste proporcional al monto del refund, restando únicamente los puntos o cashback correspondientes a ese monto.
En ambos casos el webhook emitido es
loyalty-confirmcon la resta aplicada.
Campañas
Las campañas te permiten definir las reglas bajo las cuales tus clientes acumulan puntos o cashback. Podrás crearlas y administrarlas directamente desde Dashboard.
Detalles de campaña
Define la información básica y la vigencia de la campaña.
| Campo | Descripción |
|---|---|
| Nombre de la campaña | Nombre identificador de la campaña. |
| ID de la campaña | Identificador único generado automáticamente al crear la campaña. |
| Fecha de vigencia | Rango de fechas en que la campaña estará activa. Puede tener fecha de inicio y fin, o activarse sin fecha de finalización. |
| Días de la semana (opcional) | Permite restringir la campaña a días específicos de la semana. |
| Horario (opcional) | Permite restringir la campaña a un horario específico dentro del día, con selección de zona horaria. |
created_at de cada transacción.Condiciones de campaña
Define las reglas que debe cumplir una transacción para que la campaña aplique. Puedes combinar condiciones de comercios, tarjetas y atributos de la transacción.
Condiciones disponibles por comercio:
| Condición | Descripción |
|---|---|
| Código y rubro del comercio | Filtra por MCC (Merchant Category Code). Permite incluir o excluir rubros específicos (ej: supermercados, combustible, restaurantes). Acepta tipo de filtro: incluir o excluir. |
| Nombre del comercio | Filtra por nombre del comercio. Permite definir texto que debe o no debe contener el nombre. |
Condiciones disponibles por tarjeta:
| Condición | Descripción |
|---|---|
| Marca de la tarjeta | Filtra por red de pagos (ej: Visa, Mastercard). |
| Grupo de afinidad | Filtra por el grupo de afinidad al que pertenece la tarjeta. |
| Tipo de tarjeta | Filtra por tipo de producto: Debit, Credit o Prepaid. |
Condiciones disponibles por transacción:
| Condición | Descripción |
|---|---|
| País | Filtra por el país donde se realizó la transacción. |
| Origen | Filtra por origen de la transacción: doméstica o internacional. |
| Punto de venta | Filtra por el canal o punto de venta de la transacción. |
| Presencia del dueño de la tarjeta | Indica si el titular estaba físicamente presente al momento de la compra. |
| Modo de entrada | Filtra por el modo de ingreso de la tarjeta: chip, contactless, manual, etc. |
| Presencia de la tarjeta | Indica si la tarjeta física estuvo presente o si fue una compra online/sin tarjeta. |
Recompensa y límites
Define qué recompensa recibe el member cuando cumple las condiciones, y establece topes para controlar el costo de la campaña.
Tipo de recompensa:
| Opción | Descripción |
|---|---|
| Entrega de puntos | El member acumula puntos por la transacción. |
| Cashback | El member recibe un valor monetario como recompensa. |
Modalidad de cálculo de la recompensa:
| Modalidad | Descripción | Ejemplo |
|---|---|---|
| Monto fijo | Se otorga una cantidad fija de puntos por transacción, independientemente del monto. | 100 puntos por cualquier compra |
| Puntos por monto | Se otorgan N puntos por cada X unidades monetarias gastadas. | 1000 puntos por cada $X |
| Porcentaje | Se otorga un porcentaje del monto de la transacción como puntos o cashback. | 2% del monto en puntos |
Recompensa por metas (opcional):
Puedes configurar una recompensa adicional que se entrega una sola vez por período cuando el cliente alcanza una meta de consumo o de transacciones. Se configura habilitando la opción Recompensa por metas y definiendo:
| Campo | Descripción |
|---|---|
| Meta de monto | Monto acumulado que el miembro debe alcanzar en el período para recibir la recompensa extra. |
| Meta de transacciones | Cantidad de pagos que el miembro debe realizar en el período para recibir la recompensa extra. |
| Período | Ventana de tiempo en que se evalúa la meta (por ejemplo, mensual). |
| Antigüedad del cliente (opcional) | Restringe la meta a clientes cuya antigüedad desde el alta esté dentro de un rango de días (mínimo y máximo). |
Límites de campaña:
Define un presupuesto total compartido entre todos los miembros de la campaña, que actúa como tope global. Solo se aplican los límites habilitados (con valor mayor a 0).
| Límite | Descripción |
|---|---|
| Máximos totales | Cantidad máxima de recompensas que la campaña puede repartir entre todos sus miembros, sin límite de tiempo. |
Límites de miembros:
Define cuánto puede acumular cada miembro individualmente en esta campaña. Solo se aplican los límites habilitados (con valor mayor a 0).
| Límite | Descripción |
|---|---|
| Máximo por día | Cantidad máxima de recompensa que un miembro puede acumular en un día calendario. |
| Máximo por mes | Cantidad máxima de recompensa que un miembro puede acumular en un mes calendario. |
| Máximo por año | Cantidad máxima de recompensa que un miembro puede acumular en un año calendario. |
| Máximo total | Cantidad máxima de recompensa que un miembro puede acumular en toda la campaña, sin límite de tiempo. |
| Máximo de transacciones | Cantidad máxima de transacciones de un miembro que reciben recompensa en toda la campaña. |
Audiencias
Las audiencias son listas de miembros que puedes crear y luego seleccionar dentro de la configuración de una campaña para restringir su aplicación a un grupo específico. Puedes administrarlas desde el listado de Campañas del Dashboard.
Crear una audiencia
- Ingresa a Dashboard y haz clic en la opción “Audiencias”.
- En el panel “Gestionar audiencias”, haz clic en “Crear audiencia”.
- Asigna un nombre a la audiencia.
- Sube un archivo
.CSVo.XLSX(hasta 10 MB) con una columna llamadaidentifierque contenga los identificadores de los members. - Guarda la audiencia.
Estado de las campañas
| Estado | Descripción |
|---|---|
| Active | Publicada, se evalúa en tiempo real sobre transacciones elegibles. |
| Inactive | Guardada pero no publicada, o despublicada manualmente. No aplica sobre ninguna transacción. |
Estado de los puntos
| Estado | Descripción |
|---|---|
Pending | Calculados al autorizarse, aún no acreditados. Webhook: loyalty-pending. |
Confirmed | Acreditados definitivamente tras la liquidación. Webhook: loyalty-confirm. |
Cancelled | Anulados por reversa de una transacción con puntos pendientes. No impactan el saldo. Webhook: loyalty-cancel. |
Webhooks
Te notificaremos sobre los eventos de loyalty para que puedas mantener a tus clientes informados en tiempo real. Necesitas implementar estos tres endpoints en tu sistema.
| Evento | Cuándo se envía |
|---|---|
| loyalty-pending | Al aprobar una transacción que genera puntos o cashback. Los puntos aún no están acreditados. |
| loyalty-confirm | Al liquidar la transacción o al aplicar una resta sobre puntos ya confirmados. Refleja el saldo actualizado del member. |
| loyalty-cancel | Al revertirse una transacción con puntos en estado Pending. Los puntos se anulan y no impactan el saldo. |
Para el detalle técnico de cada evento (payloads, parámetros y ejemplos), consulta la API Reference.
Visualización en Dashboard
Si configuraste un esquema de acumulación por usuario, podrás ver el balance acumulado en la sección Usuarios del Dashboard.
Si configuraste un esquema de acumulación por tarjeta, podrás consultar el balance acumulado desde la sección Tarjetas del Dashboard.
Además, desde el Detalle de cada transacción en Dashboard podrás ver si los puntos están pendientes, confirmados o cancelados.
Reposición de tarjeta
Cuando una tarjeta entra en un flujo de reposición y la nueva tarjeta queda activa, el balance acumulado se transfiere automáticamente a la nueva tarjeta. El historial de movimientos queda asociado únicamente a la nueva tarjeta; la tarjeta anterior no conserva ni muestra registro de los puntos o cashback previos.
Ajustes manuales
Vía API
Además del flujo automático, puedes acreditar o debitar puntos manualmente vía API. Esto es útil para campañas promocionales, canjes de recompensas o correcciones administrativas.
| Operación | Descripción | Identificador del member |
|---|---|---|
| MINT (Acreditación) | Acredita puntos o cashback en la cuenta del member. | card_id o user_id |
| BURN (Quita) | Debita puntos o cashback de la cuenta del member. | card_id o user_id |
Cada operación requiere una razón (reason) que queda registrada para auditoría. Para el detalle técnico de los endpoints, consulta la API Reference.
Parámetros del cuerpo de la solicitud:
| Campo | Tipo | Descripción |
|---|---|---|
clientId | string | Identificador del cliente. |
cardId | string | Identificador de la tarjeta del member. |
amount | number | Cantidad de puntos o cashback a acreditar o debitar. |
reason | string | Motivo del ajuste. Queda registrado para auditoría. |
burnType | string | Tipo de quita. Solo aplica en operaciones BURN. Valores posibles: adjustment, redeem. |
El campo burnType distingue entre una corrección operativa (adjustment) y un canje de recompensa (redeem). Para operaciones MINT este campo no aplica.
card_id como por user_id dependiendo de cuál sea tu esquema de acumulación.Desde el Dashboard
Además de la API, los usuarios con rol de administrador pueden realizar ajustes manuales directamente desde el Dashboard, sin necesidad de integración técnica adicional.
Funcionamiento
- Ingresa al Dashboard con un usuario que tenga rol de administrador.
- Navega al detalle del usuario o la tarjeta sobre la que quieres operar, según el esquema de acumulación que hayas configurado.
- Despliega el menú “Otras acciones” y selecciona “Ajustar recompensa”.
- En el modal que se abre, elige el Tipo de ajuste: “Suma” para acreditar puntos o cashback, o “Resta” para debitarlos.
- Ingresa la cantidad y completa el campo “Motivo” (obligatorio, hasta 100 caracteres).
- Confirma la operación.
Preguntas frecuentes
¿Qué pasa cuando vence el plazo para presentar una compra?
Si una presentación no llega dentro del plazo definido por la marca, cancelamos la transacción automáticamente. Los puntos o cashback en estado Pending se cancelan y te notificamos vía webhook loyalty-cancel.
¿El saldo de puntos es por tarjeta o por usuario?
Depende del esquema de acumulación que decidas configurar. Con card_id, cada tarjeta titular tiene su propio balance y las adicionales acumulan sobre ella. Con user_id, todas las tarjetas del usuario suman a un único balance visible a nivel de usuario.
¿El alta del member es inmediata al crear un usuario o tarjeta en Pomelo?
Sí, el alta es sincrónica. En el mismo momento en que se crea el usuario o tarjeta en Pomelo, el member queda disponible para acumular puntos o cashback.
¿Qué pasa con los puntos confirmados si una transacción se reversa después de haber liquidado?
Se realiza una quita automática (burn) por el monto de puntos acreditados y recibirás una notificación vía webhook loyalty-confirm con la resta aplicada.
¿Los puntos en estado Pending son visibles para ti?
Sí, podrás consultarlos dentro del detalle de la transacción en el Dashboard como puntos a impactar, pero aún no están acreditados en el balance del member.
¿Qué sucede si un member alcanzó el límite de una campaña y realiza una nueva transacción?
La transacción se procesa normalmente pero no genera puntos o cashback por esa campaña. Si hay otras campañas activas sin límite alcanzado, esas sí aplican.
¿Se puede modificar una campaña que ya está Activa?
Sí, se pueden editar sus parámetros y guardar los cambios sin necesidad de despublicarla. La campaña continúa activa con la configuración actualizada.
¿Hay un límite en la cantidad de campañas activas simultáneamente?
No hay límite. Todas las campañas activas se evalúan para cada transacción y, si aplican, sus puntos o cashback se acumulan.
¿Qué zona horaria se usa para evaluar campañas configuradas con días y horario?
La evaluación se realiza sobre el campo created_at de la transacción en UTC, independientemente del país donde se realice la transacción.
¿Se puede revertir una acreditación (mint) o quita (burn) de forma manual?
No existe reversión directa. Para corregir una acreditación o una quita, tendrás que realizar la operación inversa indicando el motivo en el campo reason.
¿Hay un límite de monto para las operaciones manuales de puntos o cashback?
No, no hay límite de monto para las operaciones manuales de acreditación o quita de puntos o cashback.
¿Qué transacciones llegan al módulo de loyalty?
Solo las transacciones autorizadas. Las transacciones rechazadas no generan ningún evento de loyalty ni puntos o cashback de ningún tipo.
¿Qué pasa con el balance de puntos o cashback cuando se repone una tarjeta?
El balance se transfiere automáticamente a la nueva tarjeta en el momento en que queda activa. La tarjeta anterior no conserva ni muestra el historial de movimientos previos. Este comportamiento aplica únicamente en esquemas de acumulación por tarjeta.
¿Qué pasa con los puntos o cashback si llega un refund parcial?
Aplicamos un ajuste proporcional al monto del refund: restamos los puntos o cashback correspondientes a ese monto sobre los ya confirmados y disparamos el webhook loyalty-confirm con la resta aplicada.
¿Puedo realizar ajustes manuales desde el Dashboard sin usar la API?
Sí, los usuarios con rol de administrador pueden hacer ajustes de suma y resta directamente desde el Dashboard, sin necesidad de integración adicional. El campo Motivo es obligatorio y cada operación queda registrada en nuestros sistemas.