Cobros recurrentes

tilopay_recurring_list_plans

Lista los planes de cobro recurrente configurados en Tilopay.

Operación del API: POST /api/v1/getPlansRepeat — ver la página de la operación

Parámetros

Sin parámetros.

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

tilopay_recurring_get_plan

Obtiene el detalle de un plan de cobro recurrente por su ID.

Operación del API: POST /api/v1/getPlanRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

tilopay_recurring_get_subscriber

Obtiene el detalle de un suscriptor de un plan recurrente por su ID.

Operación del API: POST /api/v1/getSuscriptorRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

tilopay_recurring_find_subscriber

Busca un suscriptor por nombre o correo en todos los planes recurrentes de una sola vez. Úsala antes de pausar, reactivar o editar a alguien cuando no tienes su ID.

Parámetros

Devuelve

{ result }

result = suscriptores que coinciden, cada uno con su plan_id y plan.

tilopay_recurring_subscriber_payments

Lista los pagos realizados por un suscriptor recurrente.

Operación del API: POST /api/v1/getSuscriptorPayments — ver la página de la operación

Parámetros

Devuelve

{ result }

Respuesta cruda del API de Tilopay bajo la llave `result`.

tilopay_recurring_failed_payments

Lista los últimos cobros recurrentes que fallaron (plan, suscriptor, monto, fecha y motivo en lenguaje simple). Una sola llamada basta.

Operación del API: POST /api/v1/getSuscriptorPayments — ver la página de la operación

Parámetros

Devuelve

{ total, source, failures[] }

failures = cobros recurrentes rechazados, con plan, suscriptor, monto, moneda y motivo del rechazo; total = cuántos se encontraron; source = la ruta del API de la que se obtuvieron. Combina la consulta de planes, suscriptores y sus pagos.

tilopay_recurring_manage_subscriber

Pausa, reactiva o elimina un suscriptor de un plan recurrente en Tilopay. Operación sensible: afecta cobros futuros y requiere segundo factor. Llámela primero sin `confirmation_code`: se envía un código de 6 dígitos al correo del comercio y la respuesta trae `requires_confirmation`. Repita la misma llamada agregando `confirmation_code`.

Exige confirmación: Confirmaciones que exige Tilopay

Operación del API: POST /api/v1/pauseSuscriptorRepeat, /reactiveSuscriptorRepeat o /deleteSuscriptorRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

Respuesta cruda del endpoint correspondiente a la acción: pause, reactivate o delete.

tilopay_recurring_create_plan

Crea un plan de cobro recurrente (suscripción) en Tilopay con su título, moneda, frecuencia y modalidades (nombre y monto). Devuelve el ID del plan creado; luego usa tilopay_recurring_subscription_url para obtener el enlace con el que los clientes se suscriben.

Operación del API: POST /api/v1/createPlanRepeat — ver la página de la operación

Parámetros

Devuelve

{ result, currency, frequency }

result = respuesta del API con el plan creado; currency y frequency = la moneda y la frecuencia con la que quedó el plan.

tilopay_recurring_edit_plan

Modifica un plan existente; no es edición parcial. title y frequency son obligatorios. Los campos omitidos se envían con sus valores por defecto: descripción vacía, first_amount 0, sin prueba gratis, attempts 1, webhooks y URL de agradecimiento vacíos; status omitido se envía como 1 (activo). El agente debe leer el plan con tilopay_recurring_get_plan y reenviar todos los campos. modality es opcional; si se omite se conserva el precio.

Operación del API: POST /api/v1/editPlanRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

result = respuesta del API al editar el plan; los campos omitidos se envían con sus valores por defecto, excepto modality, que conserva el precio.

tilopay_recurring_delete_plan

Elimina un plan de cobro recurrente en Tilopay. Afecta los cobros futuros del plan: confirma con el comercio antes de ejecutarla.

Exige confirmación: Confirmaciones que exige Tilopay

Operación del API: POST /api/v1/deletePlanRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

result = respuesta del API al eliminar el plan. Los suscriptores del plan dejan de cobrarse.

tilopay_recurring_subscription_url

Devuelve el enlace con el que un cliente se registra en un plan recurrente (o lo renueva si el correo ya está suscrito). Entregue la URL completa, sin recortarla.

Operación del API: POST /api/v1/recurrentUrl — ver la página de la operación

Parámetros

Devuelve

{ url, result }

url = enlace de suscripción al plan, para compartir con el cliente; result = respuesta del API tal cual.

tilopay_recurring_edit_subscriber

Cambia status (active, paused o deleted), expire (YYYY-MM-DD), modality (ID de la modalidad), amount (mayor que 0) y planId de un suscriptor; sólo envía los campos presentes. Si planId falta, se busca. La pueden usar el dueño y los empleados. No exige código por correo: para pausar, reactivar o eliminar con segundo factor existe tilopay_recurring_manage_subscriber.

Exige confirmación: Confirmaciones que exige Tilopay

Operación del API: POST /api/v1/editSuscriptorRepeat — ver la página de la operación

Parámetros

Devuelve

{ result }

result = respuesta del API al editar los campos presentes del suscriptor.

tilopay_recurring_create_coupon

Crea un cupón de descuento para un plan de suscripción: porcentaje o monto fijo, fecha de vencimiento, correos permitidos y límites de uso.

Operación del API: POST /api/v1/createCoupon — ver la página de la operación

Parámetros

Devuelve

{ result }

result = respuesta del API con el cupón de descuento creado para el plan.

tilopay_recurring_list_coupons

Lista los cupones de descuento asociados a un plan de suscripción.

Operación del API: POST /api/v1/getRepeatCoupons — ver la página de la operación

Parámetros

Devuelve

{ result }

result = cupones del plan tal cual los devuelve el API.

tilopay_recurring_get_coupon

Obtiene el detalle de un cupón de descuento por su ID.

Operación del API: POST /api/v1/getCoupon — ver la página de la operación

Parámetros

Devuelve

{ result }

result = detalle de un cupón tal cual lo devuelve el API.

tilopay_recurring_delete_coupon

Elimina un cupón de descuento de un plan de suscripción.

Exige confirmación: Confirmaciones que exige Tilopay

Operación del API: POST /api/v1/deleteCoupon — ver la página de la operación

Parámetros

Devuelve

{ result }

result = respuesta del API al eliminar el cupón.

tilopay_recurring_plan_wizard_start

Inicia el paso a paso guiado para crear (mode=create) o editar (mode=edit con plan_id) un plan de suscripción. Devuelve la primera pregunta pendiente: entréguela al comercio tal cual y pase su respuesta a tilopay_recurring_plan_wizard_answer. Úselo en vez de tilopay_recurring_create_plan cuando falte algún dato.

Parámetros

Devuelve

{ draft }

draft = borrador del plan en proceso, con lo que ya se respondió y el siguiente paso pendiente. No crea nada en Tilopay hasta confirmar.

tilopay_recurring_plan_wizard_answer

Guarda la respuesta del comercio al paso actual del plan de suscripción y devuelve la siguiente pregunta o el resumen para confirmar. Entregue el texto devuelto tal cual, sin agregar preguntas propias.

Parámetros

Devuelve

{ draft }

draft = el borrador actualizado con la respuesta del paso y el siguiente paso pendiente.

tilopay_recurring_plan_wizard_confirm

Crea o edita el plan de suscripción con los datos del paso a paso, después de que el comercio dijo sí al resumen. Al crear devuelve además el enlace de suscripción: entréguelo completo, sin recortarlo.

Operación del API: POST /api/v1/createPlanRepeat — ver la página de la operación

Parámetros

Sin parámetros.

Devuelve

{ plan_id, subscription_url }

Crea el plan con lo que se armó paso a paso: plan_id = id del plan creado; subscription_url = enlace de suscripción para compartir.

tilopay_recurring_plan_wizard_cancel

Descarta el plan de suscripción que estaba en proceso sin crear ni cambiar nada.

Parámetros

Sin parámetros.

Devuelve

Descarta el borrador del plan en proceso. No crea ni cambia nada en Tilopay; devuelve sólo la confirmación en texto.

tilopay_recurring_settle_link

Crea un enlace de pago por el monto de un cobro recurrente que falló y lo asocia al suscriptor del plan. Cuando el cliente paga ese enlace, la suscripción queda al día automáticamente: el suscriptor se reactiva y su fecha de expiración avanza al siguiente ciclo. Úsala cuando el comercio acepte enviarle el enlace al cliente de un cobro fallido (los datos salen de tilopay_recurring_failed_payments). Devuelve la URL del enlace y, si hay teléfono, un enlace de WhatsApp listo para enviarle al cliente.

Operación del API: POST /api/v1/createLinkPayment — ver la página de la operación

Parámetros

Devuelve

{ url, linkId, whatsapp_url, currency, amount, subscriber_id, frequency }

Crea un enlace de pago de un solo uso para que el suscriptor ponga al día un cobro recurrente fallido: url = enlace de pago; whatsapp_url = enlace de WhatsApp listo para enviarlo; linkId = id del enlace creado.

tilopay_recurring_settle_batch

Envío en tanda (máximo 20) de enlaces para poner al día cobros recurrentes fallidos. Primero llámala SIN confirmar: devuelve el resumen (cantidad, total, quiénes no tienen teléfono) y una huella. Muestra ese resumen TAL CUAL y pide un sí explícito. Solo si el comercio responde sí, llámala de nuevo con confirm=true y la MISMA huella. Úsala cuando pida «mandales a todos»; para un solo cliente usa tilopay_recurring_settle_link.

Parámetros

Devuelve

{ ok, preview, fingerprint, count } | { ok, created, count }

Vista previa: { ok, preview: true, fingerprint, count }. Ejecución (con confirm: true y la misma huella): { ok, created, count }.

tilopay_recurring_mark_settled

Marca al suscriptor como al día en su plan: lo deja activo y corre su fecha de expiración al siguiente ciclo. Úsala cuando el cobro pendiente ya se pagó por otro medio. Si el pago se hizo con el enlace de tilopay_recurring_settle_link, no hace falta: se actualiza solo. Confirma con el comercio antes de ejecutarla.

Operación del API: POST /api/v1/editSuscriptorRepeat — ver la página de la operación

Parámetros

Devuelve

{ ok, expire, frequency }

Corre la fecha de vencimiento del suscriptor según la frecuencia del plan, para dejarlo al día después de recuperar un cobro fallido. expire = la nueva fecha de vencimiento.