Crea un cargo calendarizado

17 noviembre 2023

Registra los datos de tarjeta de tus clientes para cobrar con la recurrencia que definas

Web

iOS

Android

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☑ Adquirente
☑ Agregador

Recibir pagos recurrentes con tarjetas de débito y crédito en tu sitio consiste en capturar la información de la tarjeta, generar un token y crear la inscripción en Kushki. Con esto, los cobros se harán automáticamente con la periodicidad que elijas.

Un ejemplo de lo que podrías integrar:

El flujo de pago que integrarás luce de la siguiente manera:

Flujo suscripción tarjeta

1. Configura tu front-end

La responsabilidad del front-end es recoger la información de tarjeta del usuario de una manera segura, tokenizarla a través de los servidores de Kushki, y luego enviarla a tu back-end para crear la inscripción de la tarjeta.

Tienes dos opciones para integrar Kushki en tu página web: Kajita y Kushki.js.

Kajita

Kushki cuenta con formularios de pago listos para recopilar información de tarjeta de forma segura. Podrás usar cualquiera de nuestras versiones:

Cajita: la primera versión del formulario de pagos. No es personalizable.
Kajita: la segunda versión. Te permite personalizar tus formularios de pago desde tu Consola de administración e incluso tener varias versiones de Kajita.

Crea y personaliza tus Kajitas

Con Kushki puedes crear tus Kajitas desde la Consola de administración. Haz clic aquí para aprender cómo hacerlo.

Configura Kajita

Incluye el script de kushki-checkout.js en tu página de pago añadiéndolo al <head> de tu archivo HTML. Siempre carga kushki-checkout directamente desde cdn.kushkipagos.com. No incluyas el script en un bundle o paquete ni hostees una copia de él.

<head>
  <title>Checkout</title>
  <script src="https://cdn.kushkipagos.com/kushki-checkout.js">       </script>
</head>

Añade Kajita a tu sitio

Kajita necesita un espacio dentro de tu página. Ingresa el siguiente código en el <body> de tu sitio donde quieras que se despliegue el formulario de pago.

Para Kajita (v.2):

<form id="my-form" action="/confirm" method="post">
    <input type="hidden" name="cart_id" value="123">
</form>

Para Cajita (v.1)

<form id="payment-form" action="/confirm" method="post">
   <input type="hidden" name="cart_id" value="123">
</form>

Recuerda configurar la acción del formulario action de acuerdo con el endpoint correspondiente en tu back-end, para obtener el token.

Luego, añade el siguiente tag script.

Para la Kajita (v.2) Podrás obtener dicho script desde tu Consola de administración según lo explicado aquí.

<script type="text/javascript">
var kushki = new KushkiCheckout({
    kformId: "HmJXukKb5",
    form: "my-form",
    publicMerchantId: "${publicCfredentialId}",// Reemplaza esto por tu credencial pública
    amount: {
     subtotalIva: 0,
     iva: 0,
     subtotalIva0: 1000,
     }
    });
</script>

Para la v.1 (Cajita), añade el siguiente script y asegúrate de que el formulario se haya cargado:

<script type="text/javascript">
    var kushki = new KushkiCheckout({
        form: "payment-form",
        merchant_id: "88ba4bff110548d09acde8d326c71253", // Reemplaza esto por tu Public Key
        amount: "14.99",
        currency: "USD",
        payment_methods:["credit-card"],
        is_subscription: true,
        inTestEnvironment: true // Configurado en modo prueba
    });
</script>

Esto creará un formulario predefinido en tu página para aceptar pagos.

Kushki.js

Usa Kushki.js si necesitas un mayor control sobre el “look & feel” o apariencia de tu formulario de pago.

Configura Kushki.js

Opción 1 - CDN

Usa el siguiente tag script al final del <body> en tu página de pagos.

<script src="https://cdn.kushkipagos.com/kushki.min.js"></script>

Option 2 - NPM

Instala el paquete desde npm.

npm install --save @kushki/js

Luego impórtalo en tu código utilizando el siguiente código.

import { Kushki } from “@kushki/js”;

Configura el objeto `Kushki`

Añade el siguiente código a tu aplicación

var kushki = new Kushki({
  merchantId: '88ba4bff110548d09acde8d326c71253', // Reemplaza esto por tu Public Key 
  inTestEnvironment: true, // Configurado en modo prueba
});

Recoge la información del usuario y envíala a tu back-end

Primero, añade el formulario a tu página de pagos con los campos requeridos. Puedes diseñarlo de la forma que mejor te parezca.

Por ejemplo:

<form id="payment-form">
  <input placeholder="Card Number" type="text" name="number">
  <input placeholder="Full Name" type="text" name="name">  
  <input placeholder="MM" type="text" name="expiry_month">
  <input placeholder="YY" type="text" name="expiry_year">
  <input placeholder="CVC" type="text" name="cvc">

  <button id="submit">Pagar $190000</button>
</form>

Luego, cuando el usuario envía el formulario, deberás solicitar el token y enviarlo a tu back-end.

kushki.requestSubscriptionToken({
  currency: "COP",
  card: {
    name: form.name,
    number: form.number,
    cvc: form.cvv,
    expiryMonth: form.expiry_month,
    expiryYear: form.expiry_year,
  },
}, (response) => {
  if(!response.code){
    console.log(response.token);
    // Submit your code to your back-end
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
});

2. Configura tu back-end

La responsabilidad del back-end es recibir el token obtenido desde tu front-end y crear la inscripción con Kushki.

Cuando el usuario envía el formulario, tu front-end transfiere un token a un endpoint que hayas especificado. Con este token, deberás realizar una llamada a nuestro endpoint del API para crear la inscripción de la tarjeta.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'POST',
  headers: [
    'Private-Merchant-Id': '0c0b08cd92fc491fb37365170164f7e9', // Reemplaza esto por tu Private Key
    'Content-Type': 'application/json'
  ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card', // Ambiente de prueba
  headers: {'content-type': 'application/json'},
  body: {
    token: 'V0OzRB100000xhxQB8035251pHLBQsq5', // Reemplaza esto por el token que recibiste
    amount: {subtotalIva: 0, subtotalIva0: 14.99, ice: 0, iva: 0, currency: 'USD'},
    planName: 'Premium',
    periodicity: 'monthly',
    contactDetails: {firstName": 'Juan', lastName: 'Flores', email: 'pruebas@kushki.com', phoneNumber: '+593984775632'},
    startDate: '2021-09-25', // Fecha del primer cobro
    metadata: {contractID: '157AB'}
  },
  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"

payload = "{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":14.99,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"planName\":\"Premium\",\"periodicity\":\"monthly\",\"contactDetails\":{\"firstName\":\"Juan\",\"lastName\":\"Flores\",\"email\":\"pruebas@kushki.com\",\"phoneNumber\":\"0984775632\"},\"startDate\":\"2021-09-25\",\"metadata\":{\"contractID\":\"157AB\"}}"

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

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

print(response.text)

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

$body = new http\Message\Body;
$body->append('{"token":"V0OzRB100000xhxQB8035251pHLBQsq5","amount":{"subtotalIva":0,"subtotalIva0":14.99,"ice":0,"iva":0,"currency":"USD"},"planName": "Premium","periodicity": "monthly","contactDetails": {"firstName":"Juan","lastName":"Flores","email":"pruebas@kushki.com","phoneNumber":"0984775632"},"startDate":"2021-09-25","metadata":{"contractID":"157AB"}}');

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

$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 tu respuesta, redirecciona al usuario a una pantalla de éxito o fracaso para informar al cliente si la inscripción se creó correctamente o si hubo un error.

Realiza una validación antifraude(Opcional)

Para la seguridad de tu comercio, el equipo de prevención de fraude de Kushki te solicitará en ciertos casos o para determinados montos activar la validación de identidad al inscribir tarjetas para realizar cargos recurrentes.

¿Cómo funciona la validación antifraude?

Cuando intentes inscribir una tarjeta, Kushki realizará una validación para verificar si el número de documento está asociado a la tarjeta de crédito enviada. En caso de que la validación sea exitosa, la inscripción se realizará correctamente, en caso contrario, esta se declinará.

Envía la información de la tarjeta

Deberás enviar la información a validación en el endpoint de creación de suscripción. Asegúrate de enviar el parámetro ignoreWarnings en false, incluir el tipo y número de documento, nombre, primer apellido y segundo apellido en el objeto contactDetails. Si por el contrario deseas omitir esta validación, envía el parámetro ignoreWarnings con valor de true.

Recibe el resultado de la validación

La respuesta de la validación de identidad la recibirás en el objeto rules con tres posibles respuestas:

Respuesta	Parámetros recibidos	¿Qué hacer?
Transación aprobada	`{"code": "000","message": "TransUnion Approval"}` `{"code": "000","message": "ExperianSignature Approval"}`	No será necesario hacer nada más, la transacción será enviada para crear la suscripción y de acuerdo a la respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si la suscripción se creó satisfactoriamente o no.
Transacción rechazada:(No fue posible realizar la validación)	`{"code": "006","message": "TransUnion Unavailable"}` `{"code": "006","message": "ExperianSignature Unavailable"}`	Verificar que se hayan enviado los parámetros `documentNumber` y `documentType` en el objeto `contactDetails` y reintentar.
Transacción rechazada	`{"code": "322","message": "TransUnion Declined"}` `{"code": "322","message": "Número de tarjeta no corresponde a la identificación dada"}`	En caso de que la transacción haya sido declinada por el sistema de validación, tendrás dos opciones: 1)Ignorar la alerta e inscribir la tarjeta: En este caso deberás volver al paso anterior, asegurándote de enviar el parámetro `ignoreWarnings` en `true` y el mismo token ya generado 2)Acatar la alerta y rechazar la transacción.

3. Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en el ambiente UAT para asegurarte de que tu integración está lista. Úsalas con cualquier CVV, código postal y fecha de expiración futura.

Transacción aprobada: 5451951574925480
Transacción declinada en solicitud de token (front-end): 4574441215190335

Si deseas probar la creación de una suscripción de una tarjeta realizando la validación antifraude, usa los números de tarjeta que se muestran a continuación al solicitar el token de inscripción y al realizar la petición de creación de la inscripción. El número de documento y tipo de documento indicados deberán incluirse dentro del objeto contactDetails.

Validación aprobada:

Tarjeta de crédito: 5642569816497595
Número de documento: 80004393
Tipo de documento: CC

Validación rechazada:

Tarjeta de crédito: 5642569816497595
Número de documento: 8000000
Tipo de documento: CC

Validación no realizada:

No enviar documentNumber ni documentType en el objeto contactDetails

4. Prepara tu certificación

Toma en consideración las siguientes pautas para aprobar la certificación técnica (requerida para obtener credenciales productivas):

Los cálculos de los impuestos están correctos.
No almacenas datos sensibles de tarjeta en tu base de datos (número completo de tarjeta, cvv, etc.).
Los mensajes que muestras en pantalla van de acuerdo con las respuestas de Kushki.
Guardas todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
La fecha del primer cobro (startDate) es una fecha futura.
La suscripción se cancela con Kushki cuando tu cliente decide cancelar sus cobros recurrentes.
Asegúrate de enviar todos los datos requeridos que se especifican en la Referencia de la API.
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.

Si estás utilizando Kushki.js, considera también lo siguiente:

El nombre del titular de la tarjeta es requerido.
El campo de número de tarjeta es requerido.
El campo de número de tarjeta acepta solo números.
El campo de número de tarjeta permite un máximo de 16 dígitos (pueden ser menos).
El campo de CVV es requerido.
El campo de CVV acepta sólo números.
El campo de CVV permite un máximo de 4 dígitos y un mínimo de 3.
La fecha de expiración es requerida.
El botón de pago se deshabilita luego de hacer el primer clic.
El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.

Maneja tus suscripciones

Edita los datos o cancela los cobros automáticos.

Acepta webhooks

Maneja eventos post-pago de la manera correcta.