Acepta un pago con tarjeta

Acepta pagos con tarjeta online de manera segura

Web
iOS
Android

Recibir pagos con tarjetas de débito y crédito en tu sitio consiste en capturar la informacion de tarjeta, crear un token y enviar el pago a Kushki para ser procesado.

Un ejemplo de un formulario de pago con tarjeta sería el siguiente:

El flujo de pago que integrarás es el siguiente:

Flujo pago con tarjeta

1. Configura tu front-end

La responsabilidad del front-end es recoger la información de tarjeta del usuario de una manera segura, tokenizar esa información a través de los servidores de Kushki y luego enviar esa información al back-end para iniciar el proceso de pago.

Tienes dos opciones para integrar: 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, agrega el 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, asegúrate de que el formulario se haya cargado:

<script type="text/javascript">
var kushki = new KushkiCheckout({
form: "payment-form",
merchant_id: "95911a50891s1cb79c0f19dd440b46bd", // Reemplázalo por tu Public key
amount: 100,
currency: "USD",
payment_methods:["credit-card"], // Podrás habilitar más medios de pago.
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

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

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_uear">
<input placeholder="CVC" type="text" name="cvc">
<button id="submit">Pay $49.99</button>
</form>

Luego, cuando el usuario envia el formulario, solicita el token y envíalo a tu back-end.

kushki.requestToken({
amount: '49.99',
currency: "USD",
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);
// 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 e iniciar el proceso de pago con Kushki.

Cuando el usuario envía el formulario, tu front-end envía un token a un endpoint que hayas especificado. Con este token, deberás realizar una llamada a nuestro endpoint de cobros para iniciar el cobro.

  • Javascript
  • Python
  • PHP
var request = require("request");
var options = {
method: 'POST',
headers: {
'Private-Merchant-Id': 'your-private-merchat-id', // Replace with your Private merchant id
'Content-Type': 'application/json'
},
url: 'https://api-uat.kushkipagos.com/card/v1/charges', // Test environment
body: {
token: "V0OzRB100000xhxQB8035251pHLBQsq5", // Replace with the token you recieved
amount: {
subtotalIva: 0,
subtotalIva0: 149900,
ice: 0,
iva: 0,
currency: "COP"
},
metadata: {
contractID: "157AB"
},
contactDetails: {
documentType: "CC",
documentNumber: "1009283738",
email: "test@test.com",
firstName: "Diego",
lastName: "Cadena",
phoneNumber: "+5730162826289"
},
orderDetails: {
siteDomain: "tuebook.com",
shippingDetails: {
name: "Diego Cadena",
phone: "+5730162826289",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Medellín",
region: "Antioquia",
country: "Colombia",
zipCode: "170402"
},
billingDetails: {
name: "Diego Osorio",
phone: "+593988734644",
address: "Eloy Alfaro 139 y Catalina Aldaz",
city: "Medellín",
region: "Antioquia",
country: "Colombia",
zipCode: "170402"
}
},
productDetails: {
product: [{
id: "198952AB",
title: "eBook Digital Services",
price: 69900,
sku: "10101042",
quantity: 1
},
{
id: "198953AB",
title: "eBook Virtual Selling",
price: 99900,
sku: "004834GQ",
quantity: 1
}
]
},
fullResponse: true
},
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/card/v1/charges"
payload = "{\"token\":\"V0OzRB100000xhxQB8035251pHLBQsq5\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":149900,\"ice\":0,\"iva\":0,\"currency\":\"COP\"},\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"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}"
headers = {'Private-Merchant-Id': 'your-private-merchat-id','Content-Type': 'application/json'}
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\":149900,\"ice\":0,\"iva\":0,\"currency\":\"COP\"},\"metadata\":{\"contractID\":\"157AB\"},\"contactDetails\":{\"documentType\":\"CC\",\"documentNumber\":\"1009283738\",\"email\":\"test@test.com\",\"firstName\":\"Diego\",\"lastName\":\"Osorio\",\"phoneNumber\":\"+593988734644\"},\"orderDetails\":{\"siteDomain\":\"tuebook.com\",\"shippingDetails\":{\"name\":\"Diego Cadena\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"zipCode\":\"170402\"},\"billingDetails\":{\"name\":\"Diego Osorio\",\"phone\":\"+593988734644\",\"address\":\"Eloy Alfaro 139 y Catalina Aldaz\",\"city\":\"Medellín\",\"region\":\"Antioquia\",\"country\":\"Colombia\",\"zipCode\":\"170402\"}},\"productDetails\":{\"product\":[{\"id\":\"198952AB\",\"title\":\"eBook Digital Services\",\"price\":69900,\"sku\":\"10101042\",\"quantity\":1},{\"id\":\"198953AB\",\"title\":\"eBook Virtual Selling\",\"price\":99900,\"sku\":\"004834GQ\",\"quantity\":1}]},\"fullResponse\":true}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/card/v1/charges');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'Private-Merchant-Id: your-private-merchat-id',
'Content-Type: application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

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

3. Prueba tu integración

Existen tarjetas de prueba que puedes utilizar en modo prueba para asegurarte que tu integración esta lista. Úsalas con cualquier CVC, código postal y una fecha de expiración en el futuro.

  • 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.).
  • Mensajes en pantalla de acuerdo a 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, como por ejemplo los detalles del producto (productDetails), así como también los datos de contacto de tu cliente-pagador (contactDetails), junto con los datos de facturación ( "orderDetails"."billingDetails") y envío (si tú modelo de negocio lo requiere: "orderDetails"."shippingDetails"), dentro del request para realizar el cargo.
  • El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.

Si estas 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 sólo números.
  • El campo de número de tarjeta 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 debe ser tipo password.
  • 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.
  • La fecha de expiración debe aceptar solamente fechas futuras.
  • El botón de pago se deshabilita luego de hacer el primer click.
  • Si tienes habilitada la opción de notificación por correo electrónico a tus clientes del resultado de transacciones desde Kushki, el parámetro email, del objeto contactDetails es requerido.
  • El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.

Acepta pagos con OTP

Sólo Web. OTP (One Time Password) es otro nivel de protección online en contra del fraude.

Acepta webhooks

Maneja eventos pospago de la manera correcta.