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 su empresa. Por ejemplo: cobrar cada 3 meses, cobrar cada 7 días, cobrar cada mes.
Mediante este servicio se puede crear una suscripción por tarjeta. En un futuro cercano agregaremos la opción para cobrar por débito directo.
Para cobrar por tarjeta, el campo collect_type debe ser charge y debe enviar el paymentToken.
En este enlace se encuentran nuestras tarjetas de prueba para ambiente de desarrollo.
Crear nueva Suscripción
URL : /v1/subscriber
Método : POST
Requiere autorización : Si, ver Autenticación
Datos requeridos para crear el plan y la suscripción simultáneamente
Datos requeridos para usar un plan existente
startDate es la fecha de inicio de la suscripción.
collectType define la forma de cobro de la suscripción. Los valores posibles son:
- sendInvoice: se le enviará al cliente enlaces para que pueda pagar por tarjeta, Rapipago o Pago Fácil
- charge: se cobrará automáticamente con la tarjeta o débito directo configurado
- free: se crea una suscripción gratuita
paymentToken es requerido si collectType = charge y desea cobrar por tarjeta. En este caso debe usar el SDK-JS de Zenrise para generar el token con los datos de la tarjeta. Ver Solicitar token de pago
bankAccount es requerido si collectType = charge y desea cobrar mediante Débito Directo a CBU.
- holderName: nombre completo del titular de la cuenta
- cbuNumber: número de CBU (no está permitido el débito directo a CVU)
- holderIdNumber: número de documento del titular del CBU
- bankId: identificador del banco. Ver Tabla de referencia de bancos
Si tiene un plan creado, puede usar el planId para especificarlo. De lo contrario, puede enviar interval, intervalCount y amount, y el sistema creará el plan o buscará uno con las mismas características para asociarlo a la suscripción.
daysAfterFirstDue: días después de la fecha de inicio para el primer vencimiento. Por defecto este valor es 10.
daysAfterSecondDue: días después 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: puede usar este parámetro para asociar cualquier información adicional a la suscripción.
Ejemplo respuesta
Suscripciones gratuitas
Para crear una suscripción gratuita debe especificar collectType como free, tal como está documentado aquí. También debe seleccionar un plan con el campo price igual a 0, o en caso de crear un plan nuevo junto con la suscripción, el campo amount debe ser 0.
Aclaración: Los webhooks siguen funcionando para suscripciones gratuitas.
Ejemplo
URL : /v1/subscriber
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
Actualización y cambio de plan de suscripciones
Una forma de modificar las suscripciones existentes es actualizando o reduciendo el precio actual. Esto se realiza cambiando el plan de la suscripción. Por ejemplo, es posible que un cliente desee cambiar de su plan básico a su plan profesional. Este tipo de acción genera una factura de prorrateo.
Ejemplo:
Suponiendo que un usuario inició su suscripción el 1/07 con 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 significa que deberá pagar el proporcional a 20 días del Plan B y se le descontará el proporcional de 20 días del Plan A que no consumirá.
- 20 días del Plan A: (1200/30) × 20 = 800. A favor: $800
- 20 días del Plan B: (2100/30) × 20 = 1400. Debe: $1400
Entonces debe pagar 1400 - 800 = $600. En ese momento se generará una factura de prorrateo por $600 que se intentará cobrar. Luego, el 1/08 recibirá una factura por $2100 del Plan B.
Si la suscripción tiene fecha de inicio a futuro (es decir, tiene estado TRIALING), entonces simplemente se actualizan los datos y no se crea una factura de prorrateo.
Aclaraciones:
- Actualmente solo está disponible cambiar a un plan con distinto precio ("price"), y con el mismo "intervalCount" e "interval". También está disponible la opción de cambiar la fecha de inicio en suscripciones a futuro (con estado TRIALING) al día de la fecha mediante el campo "startNow".
- Solo se permite un cambio de plan por período.
- La suscripción no debe haber terminado.
Actualizar plan desde una suscripción no gratuita con estado TRIALING
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
subscriptionId: identificador de la suscripción que desea actualizar.
Si tiene un plan creado puede usar el planId para especificarlo. De lo contrario, puede enviar amount y el sistema creará el plan con las características del plan anterior y con el monto actualizado.
amount: debe ser distinto de 0.
startNow: si este campo es true, se cambia la fecha de inicio de la suscripción al día de la fecha. En caso de tener webhooks asociados, recibirán la notificación de cambio de estado de TRIALING a ACTIVE en los siguientes minutos, cuando se ejecute la recurrencia.
Ejemplo respuesta
prorationInvoiceId: identificador de la factura de prorrateo. En caso de que la fecha de inicio de la suscripción sea a futuro (es decir, que esté en estado TRIALING), este campo será null.
charged: en caso de que la suscripción no sea TRIALING y sea por tarjeta de débito/crédito, se intentará cobrar la factura de prorrateo en el momento. Si se cobra exitosamente, este campo es true. Caso contrario, el campo devuelve false y la factura entra en período de reintentos (7 intentos durante 4 días). De no poder cobrarla en el período de reintentos, se cobrará en el siguiente período.
Actualizar plan desde una suscripción no gratuita con estado ACTIVE/PAST_DUE/UNPAID
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
Actualizar una suscripción gratuita a pago por tarjeta de débito/crédito con estado ACTIVE/PAST_DUE/UNPAID
Para actualizar a pago por tarjeta, debe especificar el método de pago. Esto se hace enviando collect_type igual a charge y el paymentToken.
En este enlace se encuentran nuestras tarjetas de prueba para ambiente de desarrollo.
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Actualizar una suscripción gratuita a pago por débito directo con estado ACTIVE/PAST_DUE/UNPAID
Para actualizar a pago por débito directo, debe especificar el método de pago. Esto se hace enviando collect_type igual a charge y los datos de bankAccount.
URL : /v1/subscription/change-plan
Método : POST
Requiere autorización : Si, ver Autenticación
Ejemplo respuesta
En caso de no enviar datos válidos, la API devolverá código 400 con el mensaje "Invalid body."
Ciclo de vida de una suscripción
| Estado | Descripción |
|---|---|
| TRIALING | Una suscripción se encuentra en estado TRIALING cuando la fecha de inicio es a futuro y la primera factura no está paga aún. |
| ACTIVE | La suscripción está 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. |
| UNPAID | Una suscripción está en estado UNPAID cuando hay 2 o más facturas vencidas. |
| CANCELLED | Cuando una factura llega a su segunda fecha de vencimiento y la organización tiene habilitada la cancelación automática, la suscripción pasa a CANCELLED y se deshabilitan todas las facturas futuras. |
| FINISHED | Cuando la factura llega al último período y termina su ciclo. Las suscripciones indefinidas llegan a este estado cuando usted ejecuta la finalización. |