Suscripciones y cobros únicos

La diferencia principal es que las suscripciones recurrentes permiten el cobro al cliente varias veces con un solo registro de su tarjeta: El cliente registra su método de pago una sola vez y Reveniu se encarga de cobrar automáticamente en las fechas indicadas por su intervalo. Los cobros únicos solo se crean para procesar el pago UNA sola vez al cliente.

Si el plan al que estás 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 el proceso nuevamente.

Ciclo de vida

Cobro único

1. Se genera un cobro único al momento de iniciar 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. Los cobros únicos no pueden ser reintentados, renovados o actualizados

Suscripción

Una suscripción 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. Si tiene una duración indefinida, la suscripción seguirá cobrando en su intervalo definido hasta que sea cancelada por ti o por el cliente.

Puedes ver el detalle de los estatus de una transacción en

1. Al inicio del checkout, la suscripción será creada con un status automático "Abandonada".

2. Cuando el cliente complete el checkout el estatus de la suscripción se actualizará a "No iniciada" en caso de que el registro sea exitoso.

3. 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.

4. 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¨

Sobre los urls de Suscripciones y Cobros únicos

En ambos casos, internamente se crea un modelo Suscripción, por lo que manejarás siempre el mismo url api/v1/subscriptions/ . No existen en esta versión los endpoints del tipo api/v1/onetime_payment, por ejemplo.

Objeto Suscripción

Métodos disponibles

Crear una suscripción o un cobro único, dependiendo de la frecuencia definida por el plan asociado

POST 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.

Headers

Request Body

{
    "id": 12414, 
    "completion_url": "https://reveniu.com/....",
    "security_token": "fjgj6d3hrhfh6838whfht5482"

}

curl https://integration.reveniu.com/api/v1/subscriptions/ \
  -H "Reveniu-Secret-Key: your-secret" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
      "plan_id": 123,
      "external_id": "IDENTIFICADOR_EXTERNO_1",
      "field_values": {
        "email": "usuario@gmail.com",
        "name": "Perico de los Palotes",
        // Si tu plan es de monto indefinido, debes definir el monto del cobro con este campo
        "amount": 15000,
        // Hasta aqui los parámetros obligatorios. Si deseas puedes agregar:
        "address": "Avenida de los Palotes 123, Palotes, RM, Chile",
        // Los campos de rut y ent_rut reciben strings, por lo que se puede
        //agregar el dígito verificador sin problemas y en diferentes formatos
        "rut": "1111111k",
        "ent_rut": "1111111-1" //(Rut de empresa)                                                   
        "bday": "26/10/2015",
        "phone": 1111111,
        "comuna": 1,
        "region": 1,
        "country": 1,
        "rsocial": "Razon social",        
        "comments": "Comentarios"
      }
      // Si deseas agregar campos adicionales aparte de los listados en el objeto field_values
      // (como, 'color de ojos' o 'talla de camisa', lo que necesites!)
      // Debes agregar el siguiente array (al mismo nivel de "field_values") de objetos, llamado
      // "extra_customer_fields"
      "extra_customer_fields":
        [
          {
            "name":"El nombre de primer campo custom",
            "tag_name":"identificador_en_snake_case",
            "content":"El contenido del campo" (Siempre sera un string)
          },
          {
            "name":"El nombre de otro campo custom",
            "tag_name":"identificador_del_otro_campo_en_snake_case",
            "content":"El contenido del otro campo" (Recuerda, los valores SIEMPRE seran strings)
          }
        ],
        
    ...
  }'

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();

Listar todas las suscripciones

GET https://integration.reveniu.com/api/v1/subscriptions/

Entrega la información de todas las suscripciones del comercio.

Query Parameters

Headers

[
"data": [
    {
      "id": 195,
      "status": "10",
      "interval": "3"
    },
...
]

curl https://integration.reveniu.com/api/v1/subscriptions/ \
  -H "Reveniu-Secret-Key: your-secret"

Devuelve los detalles de una suscripción

GET https://integration.reveniu.com/api/v1/subscriptions/{id}

Retorna los detalles de la suscripción.

Path Parameters

Headers

{
    "id":12414,
    "status":1,
    "cicles":10,
    "remaining_cicles":5,
    "next_due": "2023-04-07T15:00:00Z",
    "created_on": "2022-11-07T15:44:31.694097Z",
    "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,
     "payment_method": {
    "last_4_card_digits": "XXXXXXXXXXXX6623",
    "payment_method_type": "Visa"
     }
    "discount":{
                "has_discount":true,
                "rate":500,
                "is_fixed":true,
                "cicles":3
            },
    "customer":{
                "full_name":"Rafael Diaz",
                "email":"rafaeldiaz@reveniu.com",
            },
    }

curl https://integration.reveniu.com/api/v1/subscriptions/123 \
  -H "Reveniu-Secret-Key: your-secret"

Listar suscripciones asociadas a un correo electrónico

GET https://integration.reveniu.com/api/v1/subscriptions/search?email={email}

Devuelve listado de suscripciones asociada a un correo electrónico.

Path Parameters

Headers

[
{
    "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":"rafaeldiaz@reveniu.com",
            },
    }
...
]

curl https://integration.reveniu.com/api/v1/subscriptions/search?email=usuario@gmail.com \
  -H "Reveniu-Secret-Key: your-secret"

Devuelve los pagos asociados a una suscripción

GET https://integration.reveniu.com/api/v1/subscriptions/{id}/payments

Retorna los pagos pertenecientes a una suscripción

Path Parameters

Headers

[
    {
        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"}
        ...
        ]
    },

]

curl https://integration.reveniu.com/api/v1/subscriptions/{id}/payments \
  -H "Reveniu-Secret-Key: your-secret"

Listar en orden cronológico inverso todas las interacciones que ha tenido la suscripción

GET https://integration.reveniu.com/api/v1/subscriptions/{id}/interactions/

Se incluyen todas las interacciones que no sean transacciones (Ver ejemplo mas abajo).

Path Parameters

Query Parameters

Headers

// El parámetro by_staff_member será 1 
// si es una interacción realizada por el comercio
[
  {
    "created_on": "2023-03-22T19:30:41.394240Z",
    "activity_type": "6",
    "activity_type_human": "Dada de baja",
    "by_staff_member": 1
  },
  {
    "created_on": "2021-06-05T00:08:15.135394Z",
    "activity_type": "6",
    "activity_type_human": "Dada de baja",
    "by_staff_member": 0
  },
  {
    "created_on": "2021-06-02T00:09:24.889103Z",
    "activity_type": "6",
    "activity_type_human": "Dada de baja",
    "by_staff_member": 0
  },
  {
    "created_on": "2021-05-31T15:53:49.242206Z",
    "activity_type": "6",
    "activity_type_human": "Dada de baja",
    "by_staff_member": 0
  },
  {
    "created_on": "2021-05-31T15:43:49.401711Z",
    "activity_type": "6",
    "activity_type_human": "Dada de baja",
    "by_staff_member": 0
  }
]

{
  "error": "Object does not exists",
  "status_code": 404
}

Códigos de interacciones

    ('1', 'Nueva Suscripcion'),
    ('2', 'Abandono'),
    ('6', 'Dada de baja'),
    ('7', 'Recuperada'),
    ('10', 'Cancelada por el Cliente'),
    ('11', 'Cambio de metodo'),
    ('12', 'Recuperada por CC'),
    ('13', 'No autorenovar por CC'),
    ('14', 'Expirada'),
    ('15', 'Suscripcion Impaga'),
    ('16', 'Cambio de monto'),
    ('17', 'Suscripción pasa a monto personalizado'),
    ('18', 'Cambio de fecha de cobro'),
    ('19', 'Aplicado descuento de recuperacion')

Intenta recuperar una suscripción por su id

POST https://integration.reveniu.com/v1/subscriptions/reactivate/{id}

Si la suscripción tiene un estado fallido, este método activará su modo de recuperación y cambiará la próxima fecha de cobro a TODAY.

Path Parameters

Headers

{
    "result": true
}

{
  "error": "Bad request",
  "status_code": 400
}

Forzar la recuperación de un listado de suscripciones (actualización por lotes)

POST https://integration.reveniu.com/api/v1/subscriptions/reactivate/

Si se provee un listado de ids de suscripciones pertenecientes al comercio, la actualización se hará por lotes. Permite recuperar hasta 50 suscripciones a la vez.

Devuelve en el arreglo success_list los ids de las suscripciones que si pudo reactivar, y en failed_list los ids que presentaron errores

Query Parameters

Headers

{
  "result": true,
  "success_changes": [arreglo de ids],
  "failed_changes": [arreglo de ids]
}}

{
  "error": "Bad request",
  "status_code": 400
}

Extender los ciclos de cobro de una lista de suscripciones

POST https://integration.reveniu.com/api/v1/subscriptions/extend/

Se provee un listado de ids de suscripciones pertenecientes al comercio, los ciclos de las suscripciones serán reemplazados por el parámetro cicles

Ejemplo:

Si se envía el parámetro cicles=7, la suscripción pasará a tener 7 ciclos pendientes de pago.

Fecha de cobro:

En el payload se puede agregar una fecha de cobro por defecto. Si la suscripción a ser extendida tiene una fecha de cobro menor al día actual, se usará esta fecha por defecto como nueva fecha de cobro. Este caso es de utilidad cuando se desea extender suscripciones cuya fecha de cobro ya ha sido cumplida.

Si la suscripción extendida se encuentra en estado Fallido ó Expirado, será ajustada a Activa

Devuelve en el arreglo success_list los ids de las suscripciones que si pudo extender, y en failed_list los ids que presentaron errores

Request Body

{
                error: "Bad Request"
            }

Genera un pago por un monto arbitrario a una suscripción activa

POST https://integration.reveniu.com/api/v1/subscriptions/{id}/payments/authorize/

La suscripción debe pertenecer al comercio y encontrarse activa. El perfil del comercio debe tener permisos de plan PRO y sus propias credenciales habilitadas de gateway

Path Parameters

Query Parameters

{
  "result": [
    true/false, //Pago exitoso?
    true/false, // Se aplico un descuento en este pago?
    {
      "details": [
        {
          "amount": 175000,
          "status": "AUTHORIZED",
          "authorization_code": "1213",
          "payment_type_code": "VN",
          "response_code": 0,
          "installments_number": 0,
          "commerce_code": "597055555542",
          "buy_order": "202203071500001" //Orden hija 
        }
      ],
      "buy_order": "202203071500", //Orden padre
      "card_detail": {
        "card_number": "6623"
      },
      "accounting_date": "0307",
      "transaction_date": "2022-03-07T21:30:36.641Z"
    }
  ],
  "status_code": 200
}

Dar de baja una suscripción conociendo su id

POST https://integration.reveniu.com/api/v1/subscriptions/{id}/disable/

Path Parameters

{
    'result':True | False,
    'sub_id':INTEGER} 
}

{
{
    'result': False
 
}}

Desactiva la renovación de una suscripción

POST https://integration.reveniu.com/api/v1/subscriptions/{Id de sub}/disablerenew/

Permite que la suscripción quede como activa hasta su próxima fecha de cobro programada. En esa próxima fecha la suscripción no se cobrará, sino que será marcada como Expirada.

Path Parameters

Cambiar el día preferido de cobro de una suscripción

POST https://integration.reveniu.com/api/v1/subscriptions/{Id de sub}/dueday/

Se cambia el día preferido de pago de una suscripción al próximo día calendario. Ejemplo, si hoy es 20 de mayo y deseas cambiarlo a los días 15, se cambiará la próxima fecha programada al 15 de junio y se realizarán los cobros todos los 15 de cada mes a partir de ese momento.

Request Body

Enviar a un cliente el link para cambio de método de pago de una suscripción

POST https://integration.reveniu.com/api/v1/subscriptions/change_method/

Envía un correo con un link para cambiar el método de pago asociado a la suscripción o suscripciones especificadas por id en el arreglo "subs"

El link para la renovación de un método de pago tiene la siguiente estructura, en caso de que desees enviarlo por tu cuenta:

URL_DE_FRONTEND/renew/ID_DE_SUSCRIPCION

Ejemplo, para una suscripción en producción, sería:

https://app.reveniu.com/renew/ID_DE_SUSCRIPCION

Request Body

{
{'result':True,'success_changes':[120,121,122],'failed_changes':[131,132]}}

{
    {'error':'Bad request','status_code':400}
}

Cambiar el monto de cobro de una suscripción

POST https://integration.reveniu.com/api/v1/subscriptions/{id}/amount/

Request Body

{
    'result':True,
    'sub_id':Id de suscripción,
    'new_amount':Nuevo monto
}

{
    'result':False
}