Reveniu - API Docs
Search…
Reveniu - API Docs
¡[email protected] a Reveniu! 👋
API
Cómo integrar Reveniu
Cómo empezar
Autenticación
Cómo crear un plan de pagos
Cómo suscribir clientes a un plan ya creado
API RECURSOS
Planes
Suscripciones y cobros únicos
Webhooks
Variables
Ambiente Sandbox
Powered By GitBook
Suscripciones y cobros únicos
Una suscripción permite cobrar a un cliente de forma recurrente. Un cobro único permite cobrar a un cliente una sola vez.
​
En Reveniu tenemos dos tipos de planes de cobro: Cobros Recurrentes o Suscripciones; y Cobros Únicos. Esto estará determinado por el tipo de Plan al que se asocia tu cliente. Ejemplo, si asocias al cliente a un Plan de Cobro Mensual, se creará una Suscripción. Si asocias al cliente a un plan de Pago Único, se creará un Cobro Único.
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. 1.
    Se genera un cobro único al momento de iniciar el checkout
  2. 2.
    Se intenta automáticamente un cobro, recibiendo del gateway la respuesta del pago respectivo
  3. 3.
    Se registra el resultado del pago, con el estatus definido.
  4. 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.
  1. 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. 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. 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. 1.
        La suscripción realizará hasta 4 intentos totales de pago, pasando su estado a:
        1. 1.
          Failed 1 time
        2. 2.
          Failed 2 time
        3. 3.
          Failed 3 time
        4. 4.
          Failed
      2. 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. 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¨

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

Endpoints

HTTP
1
POST /api/v1/subscriptions/
2
GET /api/v1/subscriptions/
3
GET /api/v1/subscriptions/{id}/
4
GET /api/v1/subscriptions/search?email={email}
5
GET /api/v1/subscriptions/{id}/payments
Copied!

Objeto Suscripción

Objeto
JSON
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
​
post
https://integration.reveniu.com
/api/v1/subscriptions/
Crear una suscripción o un cobro único, dependiendo de la frecuencia definida por el plan asociado
​
Ejemplo
1
curl https://api.reveniu.com/api/v1/subscriptions/ \
2
-H "Reveniu-Secret-Key: your-secret" \
3
-X POST \
4
-H "Content-Type: application/json" \
5
--data '{
6
"plan_id": 123,
7
"field_values": {
8
"email": "[email protected]",
9
"name": "Perico de los Palotes",
10
// Si tu plan es de monto indefinido, debes definir el monto del cobro con este campo
11
"amount": 15000,
12
// Hasta aqui los parámetros obligatorios. Si deseas puedes agregar:
13
"address": "Avenida de los Palotes 123, Palotes, RM, Chile",
14
// Los campos de rut y ent_rut reciben strings, por lo que se puede
15
//agregar el dígito verificador sin problemas y en diferentes formatos
16
"rut": "1111111k",
17
"ent_rut": "1111111-1" //(Rut de empresa)
18
"bday": "26/10/2015",
19
"phone": 1111111,
20
"comuna": 1,
21
"region": 1,
22
"country": 1,
23
"rsocial": "Razon social",
24
"comments": "Comentarios"
25
}
26
...
27
}'
Copied!

Respuesta

{ "id": INTEGER,
"completion_url": "https://webpay3gint.transbank.cl/webpayserver/bp_multicode_inscription.cgi", "security_token": "01ab49732ee545e5c4644ad4bb8e8b538e58ea604c4b72952946d7c906986531", "status_code": 200 }
​
​
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/cobro único

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)
1
var form = document.createElement('form');
2
form.method = 'POST';
3
form.action = data.**completion_url**;
4
form.target = '_self';
5
var input = document.createElement('input');
6
input.id = 'TBK_TOKEN';
7
input.name = 'TBK_TOKEN';
8
input.type = 'hidden';
9
input.value = data.**security_token**;
10
form.appendChild(input);
11
document.body.appendChild(form);
12
form.submit();
Copied!
get
https://integration.reveniu.com
/api/v1/subscriptions/
Listar todas las suscripciones
Ejemplo
1
curl https://api.reveniu.com/api/v1/subscriptions/ \
2
-H "Reveniu-Secret-Key: your-secret"
Copied!
​
get
https://integration.reveniu.com
/api/v1/subscriptions/{id}
Devuelve los detalles de una suscripción
Ejemplo
1
curl https://api.reveniu.com/api/v1/subscriptions/123 \
2
-H "Reveniu-Secret-Key: your-secret"
Copied!
​
get
https://integration.reveniu.com
/api/v1/subscriptions/search?email={email}
Listar suscripciones asociadas a un correo electrónico
Ejemplo
1
curl https://api.reveniu.com/api/v1/subscriptions/[email protected] \
2
-H "Reveniu-Secret-Key: your-secret"
Copied!
​
get
https://integration.reveniu.com
/api/v1/subscriptions/{id}/payments
Devuelve los pagos asociados a una suscripción
Ejemplo
1
curl https://api.reveniu.com/api/v1/subscriptions/{id}/payments \
2
-H "Reveniu-Secret-Key: your-secret"
Copied!
​
post
https://integration.reveniu.com
/v1/subscriptions/reactivate/{id}
Intenta recuperar una suscripción
post
https://integration.reveniu.com
/v1/subscriptions/reactivate/
Forzar la recuperación de un listado de suscripciones (actualización por lotes)
post
https://integration.reveniu.com
/v1/subscriptions/{id}/payments/authorize/
Genera un pago por un monto arbitrario a una suscripción activa
post
https://integration.reveniu.com
/v1/subscriptions/{id}/disable/
Dar de baja una suscripción conociendo su id
post
https://integration.reveniu.com
/v1/subscriptions/{id}/amount/
Cambiar el monto de una suscripción
API RECURSOS - Previous
Planes
Next - API RECURSOS
Webhooks
Last modified 4d ago
Copy link
Contents
Ciclo de vida
Cobro único
Suscripción
Sobre los urls de Suscripciones y Cobros únicos
Endpoints
Objeto Suscripción
post
Crear una suscripción o un cobro único, dependiendo de la frecuencia definida por el plan asociado
get
Listar todas las suscripciones
get
Devuelve los detalles de una suscripción
get
Listar suscripciones asociadas a un correo electrónico
get
Devuelve los pagos asociados a una suscripción
post
Intenta recuperar una suscripción
post
Forzar la recuperación de un listado de suscripciones (actualización por lotes)
post
Genera un pago por un monto arbitrario a una suscripción activa
post
Dar de baja una suscripción conociendo su id
post
Cambiar el monto de una suscripción