Suscripciones

Una suscripción es un concepto que permite cobrar a un cliente de forma única o recurrente

Los clientes pueden iniciar una suscripción lo que activará una autorización de pago al comienzo de cada ciclo de facturación (si hablamos de un pago recurrente), esto nos permitirá capturar la informacion de pago una sola vez. Con esta información previamente registrada podremos realizar los pagos de manera rápida sin tener que ingresar los datos de pagos(Tarjeta de credito, tarjeta de debito, cuenta bancaria, etc) cada vez que se realice una compra. Los clientes también podrán cancelar una suscripción en cualquier momento.

Si el plan al que estas asociando a tu cliente es de pago único, sólo recibirás la confirmación del pago al final del proceso, pero si deseas cobrar un monto adicional el cliente deberá ingresar de nuevo sus datos e iniciar una nueva suscripción.

Ciclo de vida de una suscripción

Las suscripciones pueden ser de tipo Recurrente (Intervalos Mensuales, Semestrales, Anuales) o de Pago único (Intervalo 1 pago).

Para una suscripción de pago único

  1. Se genera la suscripción el momento de inicial el checkout

  2. Se intenta automáticamente un cobro, recibiendo del gateway la respuesta del pago respectivo

  3. Se registra el resultado del pago, con el estatus definido.

  4. Las suscripciones de 1 sólo pago no pueden ser reintentadas, renovadas o actualizadas

Para una suscripción de pago recurrente

Una suscripción recurrente es un modelo dinámico, y puede tener diferentes estados durante su proceso de vida. Típicamente una suscripción está asociada a un número de pagos exitosos que debe completar antes de renovarse o declararse expirada.

  1. Al inicio del checkout, la suscripción será creada con un status automático "Abandonada". En el transcurso de 10 minutos se intentará el 1er pago de dicha subscripción y se actualizará su status:

    1. Si el pago es exitoso, su status cambiará a "On time". Se resta 1 de los intentos de pago del total de pagos y se programa la próxima fecha de pago tomando en cuenta la fecha del pago exitoso y el intervalo configurado para la suscripción. Ejemplo, si es una suscripción mensual, se programará para el mismo día del mes siguiente.

    2. Si el pago es fallido, su status cambiará a "Failed 1 time" y se programará un intento de pago para el siguiente día calendario.

      1. La suscripción realizará hasta 4 intentos totales de pago, pasando su estado a:

        1. Failed 1 time

        2. Failed 2 time

        3. Failed 3 time

        4. Failed

      2. Si la suscripción llega a su estado Failed, no realizará mas cobros. Podrá ser reactivada si el cliente actualiza los datos de su tarjeta o si el comercio inicia un ciclo de recuperación.

  2. Al culminar su número de pagos programados, la suscripción verificará si debe ser o no renovada. De ser renovada mantendrá su estatus "On time". Si no, llegará al status ¨Expired¨

Endpoints

HTTP
HTTP
POST /api/v1/subscriptions/
GET /api/v1/subscriptions/
GET /api/v1/subscriptions/{id}/
GET /api/v1/subscriptions/search?email={email}
GET /api/v1/subscriptions/{id}/payments

Objeto Suscripción

Objeto
JSON
Objeto

ATRIBUTO

TIPO

DESCRIPCION

interval

integer

Intervalo de cobro de la suscripción

status

integer

Estatus actual de la suscripción

cicles

integer

Número de ciclos de cobro que debe completar un suscripción antes de terminarse o renovarse. -1 Si se trata de un link de cobro indefinido y auto renovable.

remaining_cicles

integer

Número de ciclos de cobro que le faltan por cobrar a la suscripción. -1 SI cicles =-1

trial_cicles

integer

Número de meses de prueba gratis que quieres agregar a un plan mensual. El número debe ser menor estricto al parámetro cicles si cicles ≠-1

link_title

string

Título del plan.

link_description

string

Descripción del plan.

is_custom_amount

boolean

Falso Si el plan tiene un monto fijo, Verdadero si tiene un monto definido por el cliente al momento del checkout.

is_uf

boolean

Verdadero Sí el cobro es con CLP, Falso sí el cobro es con UF.

plan_id

integer

Identificador del plan al que pertenece la suscripción.

is_auto_renew

boolean

Verdadero Sí la suscripción se auto renovará cuando remaining_cicles sea 0.

link_amount

number

Monto a cobrar en cada recurrencia.

discount

object

  • rate(number): Valor a descontar

  • is_fixed(boolean): Verdadero si el rate es un monto fijo, Falso si rate es un % del total

  • has_discount (boolean): Verdadero si el plan tiene un descuento asociado.

  • cicles (integer): Número de veces que se aplica el descuento al momento de ' iniciar el plan. Siempre será 1 si la suscripción es de pago único

customer

object

  • full_name (string): Nombre del Cliente

  • email(string): email del Cliente

JSON

post
Crear una suscripción

https://integration.reveniu.com/api/v1/subscriptions/
Permite iniciar una suscripción a través del API, evitándole al usuario tener que ingresar su información y permitiendo redirigir desde tu aplicación directamente a la selección de medio de pago.
Request
Response
Request
Headers
Reveniu-Secret-Key
required
string
Identificador para acceder al API.
Body Parameters
plan_id
optional
integer
Identificador único del plan al que corresponderá la suscripción.
field_values
optional
object
Datos a asociar a la suscripción.
Response
200: OK
La respuesta incluye el id de la suscripción (que puede ser consultado posteriormente), una URL donde debes dirigir al usuario para que complete la inscripción de su medio de pago. y un token de seguridad necesario para redirigir a tu cliente al formulario de registro de sus datos de pago (requerido en muchos medios de pago).
{
"id": 12414,
"completion_url": "https://reveniu.com/....",
"security_token": "fjgj6d3hrhfh6838whfht5482"
}
Ejemplo
Ejemplo
curl https://api.reveniu.com/api/v1/subscriptions/ \
-H "Reveniu-Secret-Key: your-secret" \
-X POST \
-H "Content-Type: application/json" \
--data '{
"plan_id": 123,
"field_values": {
"email": "[email protected]",
"name": "Perico de los Palotes",
"address": "Avenida de los Palotes 123, Palotes, RM, Chile"
}
...
}'

Respuesta

La respuesta incluye el id de la suscripción (que puede ser consultado posteriormente), una URL donde debes dirigir al usuario para que complete la inscripción de su medio de pago. y un token de seguridad necesario para redirigir a tu cliente al formulario de registro de sus datos de pago (requerido en muchos medios de pago). Podrás tomar el control final del flujo mediante el success_url o el failure_url del plan, pero te recomendamos siempre usar el webhook subscription_succeeded para completar en tu backend la operación (pues aún si el navegador del usuario o la conexión del usuario sufre un problema, recibirás el llamado a tu webhook).

Si no estás usando webhooks para verificar la creación de una suscripción

Al redireccionar al success_url o a failure_url que definas en cada link de pago, incluímos un parametro GET id=id__de_suscripcion. Puedes usar este parámetro para verificar que el id que recibes es en efecto el perteneciente una suscripción creada. Recuerda que al recibir esta redirección es muy probable que la suscripción aún no tenga su primer cobro, por lo que puedes esperar hasta un máximo de 10 minutos para verificar su pago. Consulta la sección Ciclo de vida de una suscripción para mas detalles.

Actualmente estamos usando Transbank como gateway de pagos de forma general en Reveniu. Tanto para los planes de pago único (WebpayPlusMall) como en los casos de pago recurrente (OneClickMall) es necesario redirigir via POST a la dirección completion_url y el parámetro TBK_TOKEN igual a security_token . Dejamos un snippet de ejemplo de cómo hacerlo automáticamente creado un formulario con javascript.

Te recomendamos que te asegures de almacenar el parámetro id que identifica a la suscripción, debido a que o bien recibirás por webhook la notificación de que la suscripción fue activada o bien puedes tu mismo preguntar por el estatus de la suscripción usando el servicio que te suministramos al efecto

Una vez que tu cliente culmine el proceso de registro será redirigido a la página de éxito o fracaso que definas para cada plan (incluyendo el parámetro id=Id de la suscripción, por GET) De no tener una página definida de éxito o fracaso en el plan que estás usando, Reveniu mostrará sus propias páginas de éxito o fracaso por defecto.

Ejemplo (Javascript)

var form = document.createElement('form');
form.method = 'POST';
form.action = data.**completion_url**;
form.target = '_self';
var input = document.createElement('input');
input.id = 'TBK_TOKEN';
input.name = 'TBK_TOKEN';
input.type = 'hidden';
input.value = data.**security_token**;
form.appendChild(input);
document.body.appendChild(form);
form.submit();

get
Listar todas las suscripciones

https://integration.reveniu.com/api/v1/subscriptions/
Entrega la información de todas las suscripciones del comercio.
Request
Response
Request
Headers
Reveniu-Secret-Key
required
string
Identificador para acceder al API.
Response
200: OK
Devuelve listado de suscripciones del comercio
[
"data": [
{
"id": 195,
"status": "10",
"interval": "3"
},
...
]
Ejemplo
Ejemplo
curl https://api.reveniu.com/api/v1/subscriptions/ \
-H "Reveniu-Secret-Key: your-secret"

get
Devuelve los detalles de una suscripción

https://integration.reveniu.com/api/v1/subscriptions/{id}
Retorna los detalles de la suscripción.
Request
Response
Request
Path Parameters
id
optional
integer
Identificador único de la suscripción.
Headers
Reveniu-Secret-Key
required
string
Identificador para acceder el API.
Response
200: OK
Devuelve una suscripción.
{
"id":12414,
"status":1,
"cicles":10,
"remaining_cicles":5,
"trial_cicles":1,
"link_title":"Plan Mensual Especial",
"link_description":"Acceso a nuestros servicios",
"is_custom_amount":false,
"is_auto_renew":true,
"link_amount":10000,
"is_uf":false,
"plan_id":101,
"discount":{
"has_discount":true,
"rate":500,
"is_fixed":true,
"cicles":3
},
"customer":{
"full_name":"Rafael Diaz",
"email":"[email protected]",
},
}
Ejemplo
Ejemplo
curl https://api.reveniu.com/api/v1/subscriptions/123 \
-H "Reveniu-Secret-Key: your-secret"

get
Listar suscripciones asociadas a un correo electrónico

https://integration.reveniu.com/api/v1/subscriptions/search?email={email}
Devuelve listado de suscripciones asociada a un correo electrónico.
Request
Response
Request
Path Parameters
email
optional
string
Correo electrónico asociado a la suscripción.
Headers
Reveniu-Secret-Key
optional
string
Identificador para acceder el API.
Response
200: OK
Retorna el listado de suscripciones asociadas a un correo electrónico
[
{
"id":12414,
"status":1,
"cicles":10,
"remaining_cicles":5,
"trial_cicles":1,
"link_title":"Plan Mensual Especial",
"link_description":"Acceso a nuestros servicios",
"is_custom_amount":false,
"is_auto_renew":true,
"link_amount":10000,
"is_uf":false,
"plan_id":101,
"discount":{
"has_discount":true,
"rate":500,
"is_fixed":true,
"cicles":3
},
"customer":{
"full_name":"Rafael Diaz",
"email":"[email protected]",
},
}
...
]
Ejemplo
Ejemplo
curl https://api.reveniu.com/api/v1/subscriptions/[email protected] \
-H "Reveniu-Secret-Key: your-secret"

get
Devuelve los pagos asociados a una suscripción

https://integration.reveniu.com/api/v1/subscriptions/{id}/payments
Retorna los pagos pertenecientes a una suscripción
Request
Response
Request
Path Parameters
id
optional
integer
Identificador único de la suscripción.
Headers
Reveniu-Secret-Key
optional
string
Identificador para acceder el API.
Response
200: OK
Retorna listado de pagos asociados a una suscripción
[
{
id: 220,
payments:[{
buy_order: 20200420220,
issued_on: "2020-04-20T23:55:14.981934Z",
amount: 1000,
credit_card_type: "VD",
is_recurrent: false,
subscription: 175,
gateway_response: "0"}
...
]
},
]
Ejemplo
Ejemplo
curl https://api.reveniu.com/api/v1/subscriptions/{id}/payments \
-H "Reveniu-Secret-Key: your-secret"