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.
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
Se genera un cobro único al momento de iniciar el checkout
Se intenta automáticamente un cobro, recibiendo del gateway la respuesta del pago respectivo
Se registra el resultado del pago, con el estatus definido.
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 Status de una suscripción
Al inicio del checkout, la suscripción será creada con un status automático "Abandonada".
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.
En el transcurso de 10 minutos se intentará el 1er pago de dicha subscripción y se actualizará su status:
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.
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.
La suscripción realizará hasta 4 intentos totales de pago, pasando su estado a:
Failed 1 time
Failed 2 time
Failed 3 time
Failed
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.
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
ATRIBUTO
TIPO
DESCRIPCION
cicles
integer
Número de ciclos de cobro que debe completar un suscripción antes de terminarse o renovarse. Si se trata de un link de cobro indefinido y auto renovable siempre aparecerá como 1
remaining_cicles
integer
Número de ciclos de cobro que le faltan por cobrar a la suscripción.
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
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 descontaris_fixed(boolean): Verdadero si el rate es un monto fijo, Falso si rate es un % del totalhas_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 Clienteemail(string): email del Cliente
last_payment
object
date Fecha del último pago procesado para esta suscripción
status: Es cero si el pago fue exitoso y diferente de cero si es fallido.
dte_type
list
Códigos de los DTE que puede generar la suscripción (sólo disponible con integración a Open Factura)
subscription_custom_fields
object list
Listado de los valores de campos custom que se definan al crear el plan
total_successful_payments
integer
Número de pagos exitosos procesados con esta suscripción
payment_method
object
payment_method_type: Visa, Mastercad, AMEX, Redcompra
last_4_card_digits String con los últimos 4 dígitos de la tarjeta asociada
external_id
string
Si deseas asociar esta suscripción a un identificador arbitrario
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
Reveniu-Secret-Key
string
Identificador para acceder al API.
Request Body
plan_id
integer
Identificador único del plan al que corresponderá la suscripción.
field_values
object
Datos a asociar a la suscripción.
extra_customer_fields
Array
Array de objetos Field si necesitas agregar campos adicionales que no están en la lista de field_values pre definidos por Reveniu
Cada campo se define como un objeto Field de esta forma:
{
"name":"El nombre del campo custom",
"tag_name":"identificador_en_snake_case",
"content":"El contenido del campo" (Siempre sera un string)
}
¡Los tres elementos del objeto son requeridos!
external_id
integer
Puedes generar un id adicional para la suscripción. Esto NO reemplazará al id generado por Reveniu, pero permite reconocer a la suscripción por un identificador adicional.
{
"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": "[email protected]",
"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)
}
],
...
}'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.
Uso de external_id
Si deseas que tu suscripcion tenga un identificador arbitrario que generes desde tu backend, puedes asignarlo. Esto NO ALTERA ni REEMPLAZA al id de la suscripción, pero siempre lo recibirás en la info de los webhooks y los demas servicios del api. No es posible realizar una busqueda por external_id en los servicios de búsqueda del api.
Cómo usar el completion_link para disparar el formulario de registro de tarjeta (Caso Transbank)
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();Listar todas las suscripciones
GET https://integration.reveniu.com/api/v1/subscriptions/
Entrega la información de todas las suscripciones del comercio.
Query Parameters
plan
Int
Filtrar por Id de plan
date_start
YYYY-m-d
Filtrar por fecha de creación (mayor o igual a )
date_end
YYYY-m-d
Filtrar por fecha de creación (menor o igual a )
Headers
Reveniu-Secret-Key*
string
Identificador para acceder al API.
[
"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
id
integer
Identificador único de la suscripción.
Headers
Reveniu-Secret-Key*
string
Identificador para acceder el API.
{
"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":"[email protected]",
},
}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
string
Correo electrónico asociado a la suscripción.
Headers
Reveniu-Secret-Key*
string
Identificador para acceder el API.
[
{
"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]",
},
}
...
]curl https://integration.reveniu.com/api/v1/subscriptions/[email protected] \
-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
id
integer
Identificador único de la suscripción.
Headers
Reveniu-Secret-Key*
string
Identificador para acceder el API.
[
{
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
*
String
Id de la suscripción
Query Parameters
date_start
YYYY-mm-dd
Fecha inicial de creación
date_end
YYYY-mm-dd
Fecha final de creación
activity
String
Código de actividad
Headers
Reveniu-Secret-Key*
String
Identificador para acceder el API.
// 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
}
]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
id*
Integer
Id de la suscripción
Headers
Reveniu-Secret-Key*
String
Identificador para acceder el API.
{
"result": true
}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
subs*
Integer []
Arreglo de identificadores de suscripción
Headers
Reveniu-Secret-Key*
String
Identificador para acceder el API.
{
"result": true,
"success_changes": [arreglo de ids],
"failed_changes": [arreglo de ids]
}}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
subs*
list
Listado de ids de suscripciones
fallback_due_date
String
Fecha por defecto en caso de que la suscripción tenga una fecha de cobro caducada. Formato DD/MM/AAAA
cicles*
integer
Número de ciclos a extender
String
auto_renew
Boolean
Permite marcar a la suscripción como Auto Renovable
{ "result": true, "success_changes": [ ids de cambios exitosos ], "failed_changes": [ids de cambios fallidos] }
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
id*
String
Id de la suscripción
Query Parameters
amount*
Integer
Monto a procesar
{
"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
id*
Integer
Identificador de la suscripción
{
'result':True | False,
'sub_id':INTEGER}
}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
id*
String
Id de la suscripción
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
new_day*
Int
Día del mes al que se quiere cambiar la fecha de cobro
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
subs*
list
Lista de ids enteros de las suscripciones a las que se desea enviar el correo
{
{'result':True,'success_changes':[120,121,122],'failed_changes':[131,132]}}Cambiar el monto de cobro de una suscripción
POST https://integration.reveniu.com/api/v1/subscriptions/{id}/amount/
Request Body
amount*
Integer
Monto al que se desea cambiar la suscripción
{
'result':True,
'sub_id':Id de suscripción,
'new_amount':Nuevo monto
}Last updated
Was this helpful?