Genera pagos one click

27 diciembre 2024

Guarda los datos de tarjeta de tus clientes para recibir pagos one click

Web

iOS

Android

Esta funcionalidad se encuentra disponible para los siguientes modelos:

☐ Adquirente
☑ Agregador

Kushki permite guardar los datos de tarjeta de un cliente de manera segura, sin necesariamente un cobro inicial, para luego permitirle realizar pagos tipo one click y así agilizar el proceso de compra.

¿Cómo funciona?

Guardar los datos de tarjetas de débito y crédito en tu app consiste en capturar la información de la tarjeta, crear un token y enviar la información a Kushki para ser guardada. Esta acción crea un identificador de inscripción de la tarjeta. Con ese identificador, desde tu back-end puedes realizar cobros one click.

Básicamente, integrar pagos one click consiste en 2 etapas: Inscripción y Cobro

El flujo que integrarás es el siguiente:

Flujo pago con tarjeta on demand

1. Inscripción

Lo primero que debes hacer para generar cobros one click es inscribir la tarjeta de tu cliente. Para realizarlo, sigue los siguientes pasos:

Configura tu app

La responsabilidad de tu aplicación 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 al back-end para iniciar el proceso de inscripción de tarjeta para que luego puedas realizar cobros one click.

Instala el SDK de Kushki

Vamos a utilizar CocoaPods para instalarlo. Si no lo tienes ya instalado, puedes obtener la última versión acá.

Incluye la librería en tu proyecto, añadiendo la siguiente línea a tu Podfile:

pod 'Kushki', '~> 2.4.2'

Luego, ejecuta el siguiente comando:

pod install

Para actualizar a la última versión ejecuta:

pod update Kushki

Configúralo

let publicMerchantId = "public-merchant-id"
let kushki = 
  Kushki(
    publicMerchantId: publicMerchantId,
    currency: "USD",
    environment: KushkiEnvironment.testing
  )

Solicita el token y envíalo a tu back-end

Una vez que el usuario ingresa su información de tarjeta en el formulario, usa el siguiente ejemplo para obtener el token y enviarlo:

private func requestSubscriptionToken(card: { //Example of what is expected in the card object
    name: "Juan Guerra",
    number: "4544980425511225",
    cvc: "345",
    expiryMonth: "12",
    expiryYear: "28"
}) {
        let publicMerchantId = "public-merchant-id"
        let kushki = Kushki(publicMerchantId: publicMerchantId,
                            currency: "USD",
                            environment: KushkiEnvironment.testing,
                            false)//optional parameter regional
        kushki.requestSubscriptionToken(card: card)
            {DispatchQueue.main.async(execute: {
                let alert = UIAlertController(title: "Kushki Token",
                                              message: message,
                                              preferredStyle: UIAlertControllerStyle.alert)
                alert.addAction(UIAlertAction(title: "Ok", style: .default))
                self.present(alert, animated: true)
            })
          }
    }

Configura tu back-end

La responsabilidad del back-end es recibir el token obtenido desde tu front-end e iniciar el proceso de inscripción de tarjeta 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 de inscripción para inscribir la tarjeta.

Javascript
Python
PHP

const request = require("request");

const options = {
  method: 'POST',
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card',
  headers: {'content-type': 'application/json'},
  body: {
    token: 'gV3ox6100000sAxClU033646vnnJsT83',
    planName: 'Gold',
    periodicity: 'custom',
    contactDetails: {
      "documentType": "CC",
      "documentNumber": "1009283738",
      "email": "test@test.com",
      "firstName": "Diego",
      "lastName": "Cadena",
      "phoneNumber": "+593988734644"
    },
    amount: {
      subtotalIva: 0, 
      subtotalIva0: 14.99, 
      ice: 0, 
      iva: 0.14, 
      currency: 'USD'
    },
    startDate: '2021-01-01',
  },
  json: true
};

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

  console.log(body);
});

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

payload = "{\"token\":\"gV3ox6100000sAxClU033646vnnJsT83\",\"planName\":\"Premium\",\"periodicity\":\"custom\",\"contactDetails\":{\"firstName\":\"Juan\",\"lastName\":\"García\",\"email\":\"pruebas@kushki.com\"},\"amount\":{\"subtotalIva\":1,\"subtotalIva0\":0,\"ice\":0,\"iva\":0.14,\"currency\":\"USD\"},\"startDate\":\"2018-09-25\",\"metadata\":{\"plan\":{\"fitness\":{\"cardio\":\"include\",\"rumba\":\"include\",\"pool\":\"include\"}}}}"

headers = { 'content-type': "application/json" }

conn.request("POST", "/subscriptions/v1/card", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

# Tu lógica acá ...

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

$body = new http\Message\Body;
$body->append('{"token":"gV3ox6100000sAxClU033646vnnJsT83","planName":"Premium","periodicity":"custom","contactDetails":{"firstName":"Juan","lastName":"García","email":"pruebas@kushki.com"},"amount":{"subtotalIva":1,"subtotalIva0":0,"ice":0,"iva":0.14,"currency":"USD"},"startDate":"2018-09-25","metadata":{"plan":{"fitness":{"cardio":"include","rumba":"include","pool":"include"}}}}');

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

$request->setHeaders(array(
  'content-type' => 'application/json'
));

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

echo $response->getBody();

// Tu lógica acá ...

De acuerdo con tu respuesta, redirecciona al usuario a una página de éxito o fracaso para informar al cliente si la inscripción fue aprobada o declinada.

2. Cobro

Una vez que ya tengas inscrita la tarjeta de tu cliente, para realizar un cobro, es necesario realizar estos sencillos pasos, utilizando el subscriptionId.

Configura tu front-end

Primero debemos importar y configurar la librería Kushki.js. Después utilizaremos un método que será de mucha ayuda para verificar la fiabilidad del cobro.

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>

Opción 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

const kushki = new Kushki({
  merchantId: 'public-merchant-id', // Your public merchant id 
  inTestEnvironment: true,
});

Genera un token de cobro y envíalo a tu back-end

Primero, es necesario obtener el id de suscripción de la tarjeta a la que se realizará el cobro.

Luego, solicita el token de cobro y envíalo a tu back-end.

kushki.requestDeviceToken({
  subscriptionId: "1543267242354000" // Replace with your subscription id
}, (response) => {
  if(response.code){
    console.log(response);
    // Submit your code to your back-end
  } else {
    console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
  }
});

Configura tu back-end

Una vez que ya tengas inscrita la tarjeta de tu cliente, para realizar un cobro one click basta llamar a nuestro endpoint de cobros junto con el subscriptionId bajo la lógica que definas.

Javascript
Python
PHP

var request = require("request");

var options = {
  method: 'POST',
  headers: [
            'Private-Merchant-Id': '' // Reemplaza con tu Private merchant id
        ]
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/291929129192912', // Reemplázalo con tu id de suscripción
  headers: {'content-type': 'application/json'},
  body: {
  language: "es",
  token: "1cfaze100000qQ4dtN016410Ow7ot8nd",
  amount: {
    subtotalIva: 0,
    subtotalIva0: 49.99,
    ice: 0,
    iva: 0,
    currency: "USD"
  },
  deferred: {
    graceMonths: "02",
    creditType": "01",
    months: 6
                },
  metadata: {
    customerId: "123"
  },
  contactDetails: {
    documentType: "CC",
    documentNumber: "1009283738",
    email: "test@test.com",
    firstName: "Diego",
    lastName: "Cadena",
    phoneNumber: "+593988734644"
  },
  orderDetails: {
    siteDomain: "tuebook.com",
    shippingDetails: {
      name: "Diego Cadena",
      phone: "+593988734644",
      address: "Eloy Alfaro 139 y Catalina Aldaz",
      city: "Quito",
      region: "Pichincha",
      country: "Ecuador",
      zipCode: "170402"
    },
    billingDetails: {
      name: "Diego Cadena",
      phone: "+593988734644",
      address: "Eloy Alfaro 139 y Catalina Aldaz",
      city: "Quito",
      region: "Pichincha",
      country: "Ecuador",
      zipCode: "170402"
    }
  },
  productDetails: {
    product: [
      {
        id: "198952AB",
        title: "eBook Digital Services",
        price: 6990000,
        sku: "10101042",
        quantity: 1
      },
      {
        id: "198953AB",
        title: "eBook Virtual Selling",
        price: 9990000,
        sku: "004834GQ",
        quantity: 1
      }
    ]
  },
  fullResponse: true
},
  json: true
};

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

  console.log(body);
});

import requests

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

payload = "{\"language\":\"es\",\"token\":\"1cfaze100000qQ4dtN016410Ow7ot8nd\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":49.99,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"deferred\":{\"graceMonths\":\"02\",\"creditType\":\"01\",\"months\":3},\"metadata\":{\"customerId\":\"123\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Cadena\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Quito\",\"region\":\"Pichincha\",\"country\":\"Ecuador\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Quito\",\"region\":\"Pichincha\",\"country\":\"Ecuador\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":6990000,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9990000,\"sku\":\"004834GQ\",\"quantity\":1}]}}"

headers = { 'content-type': "application/json" }

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

print(response.text)

# Tu lógica acá ...

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

$body = new http\Message\Body;
$body->append('{\"language\":\"es\",\"token\":\"1cfaze100000qQ4dtN016410Ow7ot8nd\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":49.99,\"ice\":0,\"iva\":0,\"currency\":\"USD\"},\"deferred\":{\"graceMonths\":\"02\",\"creditType\":\"01\",\"months\":3},\"metadata\":{\"customerId\":\"123\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Cadena\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Quito\",\"region\":\"Pichincha\",\"country\":\"Ecuador\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Quito\",\"region\":\"Pichincha\",\"country\":\"Ecuador\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":6990000,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":9990000,\"sku\":\"004834GQ\",\"quantity\":1}]}}');

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

$request->setHeaders(array(
  'content-type' => 'application/json'
));

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

echo $response->getBody();

// Tu lógica acá ...

Cancela una inscripción (Opcional)

Si tu cliente decide cancelar el servicio o una vez que dejes de darlo, para cancelar el guardado de la tarjeta, simplemente debes llamar a nuestro endpoint de cancelación de inscripción desde tu backend.

Javascript
Python
PHP

const request = require("request");

request({
  method: 'DELETE',
  url: 'https://api-uat.kushkipagos.com/subscriptions/v1/card/213123123123',
  headers: {'content-type': 'application/json'}
}, (error, response, body) => {
  if (error) throw new Error(error);

  console.log(body);
  // Tu lógica acá ...
});

import http.client

conn = http.client.HTTPSConnection("api-uat.kushkipagos.com")

headers = { 'content-type': "application/json" }

conn.request("DELETE", "/subscriptions/v1/card/213123123123", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

# Tu lógica acá ...

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

$request->setRequestUrl('https://api-uat.kushkipagos.com/subscriptions/v1/card/213123123123');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'content-type' => 'application/json'
));

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

echo $response->getBody();
// Tu lógica acá ...

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
Transacción declinada en solicitud de cobro (back-end): 4349003000047015

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 almacenar datos sensibles de tarjeta en tu base de datos (número completo de tarjeta, CVV, etc.).
Mostrar mensajes en pantalla de acuerdo con las respuestas de Kushki.
Guardar y registrar todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
Asegúrate de enviar todos los datos requeridos que se especifican en la Referencia de la API.
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 tiene un máximo de 16 dígitos (pueden ser menos).
El campo de CVV es requerido.
El campo de CVV acepta solo números.
El campo de CVV permite un máximo de 4 dígitos y un mínimo de 3.
El campo de CVV debe ser tipo password.
La fecha de expiración es requerida.
La fecha de expiración debe aceptar solamente fechas futuras.
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í.
Asegúrate de enviar los datos de contacto de tu cliente-pagador (contactDetails), junto con los datos de facturación ( orderDetails -> billingDetails) y envío (si tu modelo de negocio lo requiere: orderDetails -> shippingDetails), dentro del request para realizar el cargo. El ejemplo del Body del JSON para el charge, lo podrás encontrar en Referencia de la API.

Acepta webhooks

Maneja eventos pospago de la manera correcta.

Esta funcionalidad se encuentra disponible para los siguientes modelos:

¿Cómo funciona?

1. Inscripción

Configura tu app

Instala el SDK de Kushki

Configúralo

Solicita el token y envíalo a tu back-end

Configura tu back-end

2. Cobro

Configura tu front-end

Configura Kushki.js

Opción 1 - CDN

Opción 2 - NPM

Configura el objeto Kushki

Genera un token de cobro y envíalo a tu back-end

Configura tu back-end

Cancela una inscripción (Opcional)

3. Prueba tu integración

4. Prepara tu certificación

Acepta webhooks

Configura el objeto `Kushki`