Maneja tus cargos calendarizados

19 enero 2024

Actualiza los datos de un cargo calendarizado, aplica descuentos o cancela los cobros automáticos

Kushki te permite manejar los cargos recurrentes calendarizados existentes de tus clientes sin necesidad de crearlos nuevamente. Esto te ayudará a mantener el mismo ID de suscripción luego de los cambios. Las acciones más comunes son:

• Obtener los datos de una cargo calendarizado.
• Actualizar la información de un cargo calendarizado: monto, recurrencia, etc.
• Especificar un descuento en el monto cobrado por un número de períodos definido.
• Cancelar los cobros recurrentes.

Obtén los datos de un cobro calendarizado

Puedes consultar los datos disponibles de un cargo calendarizado que ya fue creado para que luego los muestres en pantalla a tus clientes. La información que devolvemos también la puedes guardar en tus bases de datos; no tendrás problemas, ya que no te daremos datos sensibles de la tarjeta.

Primero deberás identificar el ID de la inscripción de la cual quieres consultar los datos. Luego, realiza una llamada a nuestro endpoint de consulta de información de cargo calendarizado desde tu back-end e incluye el ID de inscripción como path parameter.

var request = require("request");

var options = {
  method: 'GET',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000', // Ambiente de prueba
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000"

payload = {}

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Reemplaza esto por tu Private Key
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/search/1591842658589000');
$request->setRequestMethod('GET');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

De acuerdo con la respuesta, muestra en pantalla la información que necesites o guárdala en tus bases de datos.

Actualiza la información del cargo calendarizado

Cuando tienes un cambio en el plan recurrente de tus clientes, puedes actualizar la información del cargo calendarizado que ya está creado sin necesidad de pedir nuevamente los datos de la tarjeta.

Los datos que puedes actualizar son:

• Nombre del plan
• Recurrencia con la que se ejecutan los cobros (periodicity)
• Datos de contacto
• Monto a cobrar
• Fecha en la que se cobra (startDate)
• Fecha de finalización de los cargos calendarizados (endDate)
• Lógica de reintentos de cobro

Primero deberás identificar el ID de inscripción que quieres actualizar. Luego, realiza una llamada a nuestro endpoint de actualización de cargos calendarizados desde tu backend e incluye el ID de inscripción como path parameter.

Asegúrate de enviar solo la información que necesitas cambiar para que el resto de datos del cargo calendarizado se mantengan. Por ejemplo, cuando uno de tus clientes que tiene el plan Básico de 10 USD mensuales quiere cambiarse al plan Profesional por 35 USD mensuales, solamente deberás enviar el valor y el nombre del nuevo plan en el llamado a nuestro endpoint.

var request = require("request");

var options = {
  method: 'PATCH',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Ambiente de prueba
  headers: {'content-type': 'application/json'}
  body: {
    amount: {subtotalIva: 0, subtotalIva0: 35, ice: 0, iva: 0, currency: 'USD'},
    planName: 'Profesional'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = "{\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":35,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"planName\":\"Profesional\"}"

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Reemplaza esto por tu Private Key
}

response = requests.request("PATCH", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"amount":{"subtotalIva":0,"subtotalIva0":35,"ice":0,"iva":0,"currency":"USD"},"planName": "Profesional"}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('PATCH');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

De acuerdo a la respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si el cargo calendarizado se actualizó correctamente o si hubo un error.

Actualiza la información del pago de un cargo calendarizado

Si por algún motivo requieres actualizar el método de pago de una suscripción (por ejemplo, una tarjeta venció, la tarjeta fue actualizada o reemplazada, saldo insuficiente, etc.) puedes actualizar los datos de la tarjeta sin que la información de la suscripción se modifique (periodicidad, monto, detalles de la suscripción, etc.). Dependiendo el tipo de integración, es necesario enviar los datos de la tarjeta nueva para obtener un token y posteriormente enviar el token obtenido en el endpoint actualizar datos de la tarjeta en un cargo recurrente.

Integración Kushki.js (front end)

Si estás obteniendo el token desde tu front end con la biblioteca de Kushki.js, sigue los pasos detallados a continuación:

Consume el método requestSubscriptionToken()

En tu implementación de Kushki.js, es necesario que consumas el método requestSubscriptionToken() disponible en la biblioteca, enviando los parámetros requeridos.

var callback = function(response) {
  if(!response.code){
    console.log(response.token);
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
}

kushki.requestSubscriptionToken({
  card: {
    name: "Juan Guerra",
    number: "4544980425511225",
    cvc: "345",
    expiryMonth: "12",
    expiryYear: "28"
},
  currency: "USD"
}, callback); // Also you can set the function directly

Si la solicitud ha sido correcta, recibirás una respuesta con el token como se muestra a continuación

{ 
  "token": "90a9f2d93ba508c38971890454897fd4"
}

Para más información, consulta la implementación del método requestSubscriptionToken.

Actualiza datos de la tarjeta en un cargo recurrente

Si la generación del token ha sido correcta, debes de consumir el endpoint actualiza datos de la tarjeta en un cargo recurrente enviando el token obtenido en el paso anterior y el subscriptionId con el id de la suscripción a actualizar.

Para más información, consulta la implementación del endpoint actualiza datos de la tarjeta en un cargo recurrente

Integración API (back end)

En tu implementación mediante API, es necesario que consumas el endpoint solicitar un token de cargo recurrente, enviando los datos de la tarjeta.

Para más información, consulta la implementación del endpoint solicitar un token de cargo recurrente

Actualiza datos de la tarjeta en un cargo recurrente

Si la generación del token ha sido correcta, debes de consumir el endpoint actualiza datos de la tarjeta en un cargo recurrente enviando el token obtenido en el paso anterior y el subscriptionId con el id de la suscripción a actualizar.

Para más información, consulta la implementación del endpoint actualiza datos de la tarjeta en un cargo recurrente

Aplica un descuento temporal

Kushki te permite ofrecer períodos con descuentos a tus clientes. Una vez que se cumpla el período que especificas, automáticamente cobraremos a la tarjeta el valor original con el que se creó el cargo calendarizado.

Primero deberás identificar el ID del cargo calendarizado (o ID de inscripción) al que se aplicará el descuento. Luego, realiza una llamada a nuestro endpoint de descuentos temporales en cargos calendarizados desde tu back-end e incluye el ID de inscripción como path parameter.

El valor que especifiques será el monto que Kushki cobrará a la tarjeta durante el número de períodos indicado. Por ejemplo, tu cliente inscribió su tarjeta y autorizó un cargo de 30 USD mensuales; para que Kushki cobre 20 USD durante dos meses, envía el monto y el número 2 en la cantidad de períodos.

var request = require("request");

var options = {
  method: 'PUT',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Ambiente de prueba
  headers: {'content-type': 'application/json'}
  body: {
    amount: {subtotalIva: 0, subtotalIva0: 20, ice: 0, iva: 0, currency: 'USD'},
    periods: 2
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = "{\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":20,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"periods\":2}"

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Reemplaza esto por tu Private Key
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"amount":{"subtotalIva":0,"subtotalIva0":20,"ice":0,"iva":0,"currency":"USD"},"periods":20}');

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('PUT');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

De acuerdo con la respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si el descuento se aplicó correctamente o si hubo un error.

Cancela los cobros recurrentes

Cuando tu cliente decida cancelar el cargo recurrente, asegúrate de cancelarla también con Kushki para que los cobros calendarizados ya no se ejecuten. Esta acción es inmediata; una vez que la ejecutes, la suscripción quedará automáticamente cancelada.

Primero deberás identificar el ID de inscripción del cargo que quieres cancelar. Luego, realiza una llamada a nuestro endpoint de cancelación de cargos recurrentes desde tu backend e incluye el ID de inscripción como path parameter.

var request = require("request");

var options = {
  method: 'DELETE',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000', // Ambiente de prueba
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000"

payload = {}

headers = {'Content-Type': 'application/json',
  'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9' // Reemplaza esto por tu Private Key
}

response = requests.request("DELETE", url, headers=headers, data=payload)

print(response.text)

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/1591842658589000');
$request->setRequestMethod('DELETE');

$request->setHeaders(array(
  'Private-Merchant-Id' => '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
  'Content-Type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

De acuerdo con la respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si el cargo calendarizado se canceló correctamente o si hubo un error.