Suscripción
Conceptos Generales
Las suscripciones le permiten cobrar a un cliente de forma recurrente con la periodicidad y el tiempo que su negocio necesite.
Actualmente permitimos periodicidad:
- diaria
- mensual
- anual
Para cualquiera de las 3 opciones el intervalo es definido por la empresa cobradora. Ej: Cobrar cada 3 meses, cobrar cada 7 días, cobrar cada 1 mes.
En este mismo endpoint se puede crear una suscripción por tarjeta en un futuro cercano agregaremos para poder cobrar por debito directo.
Para cobrar por tarjeta collect_type debe ser charge y paymentToken debe ser enviado.
En este link se encuentran nuestras tarjetas de prueba. Ver tarjetas de prueba
Crear nueva Suscripción
URL : /v1/subscriber
Método : POST
Requiere autorización : Si, ver Autenticación
Modelo de datos que crea el plan al mismo tiempo que crea la suscripción
Modelo de datos que usa un plan previamente creado
startDate es la fecha de inicio de la suscripción.
collectType es el tipo de como se va a cobrar la suscripción, este podría ser sendInovice, charge o free es decir si se elige sendInvoice se le enviara al cliente unos links para que pueda pagar por tarjeta rapipago o pago fácil, si se usa charge se cobrara automáticamente con la tarjeta que se realiza el primer pago y si se usa free entonces se crea una subscripción gratuita.
paymentToken es requerido si el collectType = charge y queremos cobrar por tarjeta, en este caso tenemos que usar el sdk-js de Zenrise para poder generar esta entidad con los datos de la tarjeta. Ver Solicitar token de pago
bankAccountDto es requerido si el collectType = charge y queremos cobrar mediante Debito Directo a CBU.
holderName representa el nombre del cliente.
cbuNumber numero de CBU, no esta permitido el debito directo a CVU.
holderIdNumber numero de documento de el titular del CBU.
bankId Ver Tabla referencia bancos
Si tenemos un plan creado podemos usar el planId para especificarlo, de lo contrario podemos pasar interval, intervalCount y amount entonces nosotros nos encargamos de crear el plan o buscar un plan con las mismas características para asociarlo a la subscripción.
daysAfterFirstDue dias despues de la fecha de inicio para el primer vencimiento por defecto este valor es 10.
daysAfterSecondDue dias despues de la primera fecha de vencimiento para el segundo vencimiento por defecto este valor es 10.
firstDuePercentage porcentaje de recargo a aplicar luego de la primera fecha de vencimiento por defecto este valor es 0.
secondDuePercentage porcentaje de recargo a aplicar luego de la segunda fecha de vencimiento por defecto este valor es 0.
metadata se puede usar este parametro para asociar cualquier informacion extra a la suscripcion
Ejemplo respuesta
Suscripciones gratuitas
Para crear una suscripcion gratuita se debe especificar en el campo collectType, como esta documentado aca, tambien se debe seleccionar un plan con el campo price igual a 0, o en caso de crear un plan nuevo junto con la suscripcion, el campo amount debe ser 0.
Aclaración: WebHooks siguen funcionando para suscripciones gratuitas.
Ejemplo
URL : /v1/subscriber
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
Upgrade y Downgrade de suscripciones
Una forma de modificar las suscripciones existentes es actualizando o rebajando el precio actual, esto se realiza cambiando el plan de la suscripcion. Por ejemplo, es posible que un cliente desee cambiar de su oferta básica a su oferta profesional, este tipo de accion genera una factura de prorrateo.
Por ejemplo: Suponiendo que un usuario que inicio su suscripción el 1/07 para el Plan A (su próxima fecha de cobro será el 1/08). El día 10/07 el usuario decide cambiarse al plan B. Esto quiere decir que deberá pagar el proporcional a 20 días del plan B y se le restará el proporcional de 20 días del plan A que el usuario no consumirá.
20 días de plan A: (1200/30)20 = 800. A favor: $800 20 días del plan B: (2100/30)20 = 1400. Debe: $1400
Entonces deber apagar 1400-800=600. En ese momento se va a generar una factura de prorrateo por $600 se intentara cobrar y luego el 1/08 ya le llegara una factura por $2100 del plan B nuevo. Si la suscripcion tiene startDate a futuro (es decir tiene status TRIALING), entonces simplemente se actualizan los datos y no se crea una factura de prorrateo.
Aclaraciones:
- Actualmente solo esta disponible cambiar a un plan con distinto "price", y con el mismo "intervalCount" e "interval". Tambien esta disponible la opcion de cambiar startDate en suscripciones a futuro (con status TRIALING) al dia de la fecha mediante el campo "startNow".
- Solo se permite un cambio de plan por periodo.
- Suscripcion no debe haber terminado.
Upgrade desde una suscripcion no gratuita y con status TRIALING
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
subscriptionId suscripcion que se quiere hacer Upgrade.
Si tenemos un plan creado podemos usar el planId para especificarlo, de lo contrario podemos pasar amount entonces nosotros nos encargamos de crear el plan con las caracteristicas del plan anterior y con el monto actualizado. amount debe ser distinto de 0
startNow si este campo es true, se cambia el startDate de la subscripcion al dia de la fecha. En caso de tener Webhooks asociados, recibiran la notificacion de paso de subscripcion de TRIALING a ACTIVE en los siguientes minutos, cuando se ejecute la recurrencia.
Ejemplo respuesta
prorationInvoiceId id de la factura de prorrateo. En caso de que la fecha de inicio de la suscripción sea a futuro (es decir que esta en status TRIALING) este campo vendrá como null.
charged en caso de que la suscripcion no sea TRIALING y sea por tarjeta de debito/credito, se intentara cobrar la factura de prorrateo en el momento, de haberse cobrado exitosamente, este campo es true, caso contrario, el campo devuelve false y la factura entra en periodo de reintentos, es decir reintentaremos cobrarla 7 veces durante 4 días. De no poder cobrarla en el periodo de reintentos, se cobrara en el siguiente periodo.
Upgrade desde una suscripcion no gratuita y con status ACTIVE/PAST_DUE/UNPAID
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
Upgrade de una suscripcion gratuita a una por tarjeta de debito/credito y con status ACTIVE/PAST_DUE/UNPAID
Para hacer un Upgrade por tarjeta, hay que especificar el metodo de pago, esto se hace enviando collect_type igual a charge y paymentToken debe ser enviado.
En este link se encuentran nuestras tarjetas de prueba. Ver tarjetas de prueba
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Upgrade de una suscripcion gratuita a una por debito directo y con status ACTIVE/PAST_DUE/UNPAID
Para hacer un Upgrade por tarjeta, hay que especificar el metodo de pago, esto se hace enviando collect_type igual a charge y paymentToken debe ser enviado.
En este link se encuentran nuestras tarjetas de prueba. Ver tarjetas de prueba
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
En caso de no enviar un Body valido, el API devolera 400 con el mensaje "Invalid body."
Downgrade
En progreso.
Ciclo de vida de una Suscripcion
| Estados | Descripción |
|---|---|
| TRIALING | Una suscripción se encuentra en estado de TRIALING cuando la fecha de inicio es a futuro y la primer factura no esta paga aún. |
| ACTIVE | La suscripción esta al día con todos sus pagos realizados correctamente. |
| PAST_DUE | Una suscripción se encuentra en estado PAST_DUE si tiene exactamente una factura vencida o en periodo de reintentos de pago, para el caso de las suscripciones que se cobran por tarjeta. |
| UNPAID | Una suscripción esta en periodo de UNPAID cuando hay 2 o mas facturas vencidas y/o en periodo de reintentos. |
| CANCELLED | Cuando una factura llega al máximo de reintentos de pagos (si la organización tiene habilitada la configuración pasa a CANCELLED, PAST_DUE o UNPAID), la suscripción pasa a cancelada y se deshabilitan todas las facturas futuras. |
| FINISHED | Cuando la factura llega al ultimo periodo y termina su ciclo. Las suscripciones indefinidas llegan a este estado cuando usted ejecuta la finalización |