Recibe transferencias bancarias

Tus clientes podrán usar el saldo de su cuenta bancaria para comprar en tu sitio web

Web
iOS
Android

Permite que tus clientes aprovechen el saldo disponible en su cuenta bancaria para adquirir tus productos y/o servicios desde tu página web, a través de PSE. Para lograrlo, debes habilitar el listado de bancos disponibles en Colombia, obtener los datos basicos de tu cliente pagador y direccionarlos al sitio de su sucursal bancaria virtual, para realizar el débito a la cuenta bancaria.

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

Flujo pago con transferencia (CO)

1. Configura tu Front-end

La responsabilidad del front-end es recolectar los datos principales del usuario, tokenizar esa información a través de los servidores de Kushki y luego enviarla al back-end para iniciar el proceso de pago.

Para ello cuentas con dos opciones: Cajita y Kushki.js.

Cajita

Usa Cajita para simplicar tu integración y recolectar los datos de pago de tu cliente.

Configura Cajita

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 o hostees una copia de él.

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

Añade Cajita a tu sitio

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

<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 al endpoint correspondiente en tu back-end, para obtener el token.

Luego, agrega el siguente tag script. Asegurándote 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: {
"subtotalIva": 0, // define el valor 0 cuando la Tx no tiene impuestos
"iva":0, // define el valor 0 cuando la Tx no tiene impuestos
"subtotalIva0": 100, // Define el valor total de la Tx en caso de que no tenga impuestos, de lo contrario configura 0
"ice": 0 // define el valor 0 en caso de que la Tx no tenga ICE (Impuesto a consumos especiales)
},
currency: "USD",
payment_methods:["transfer"], // Podrás habilitar más medios de pago.
inTestEnvironment: true, // Configurado en modo prueba
callback_url: "https://return.com" // La URL a la que será retornado el cliente al terminar el pago en el sitio del banco. NO requerido para MX
});
</script>

Esto creará un formulario pre-definido 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,
});

Solicita el listado de bancos

Antes de generar el token, necesitas cargar el listado completo de bancos disponibles en PSE, para que el cliente pagador pueda seleccionar la entidad para efectuar la transferencia:

var callback = function(response) {
if(!response.code){
console.log(response);
} else {
console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
}
}
kushki.requestPseBankList(callback); // Also you can set the function directly

Recolecta 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 como desees.

Por ejemplo:

<form id="payment-form">
<input placeholder="Nombre" type="text" name="name">
<input placeholder="Tipo de persona" type="text" name="userType">
<input placeholder="CC" type="text" name="DocumentType">
<input placeholder="Número de documento" type="text" name="DocumentNumber">
<input placeholder="Referencia" type="text" name="Reference">
<input placeholder="Descripcion" type="text" name="Description">
<button id="submit">Pay $49.99</button>
</form>

Luego, cuando el usuario envía el formulario, tu solicitas el token y lo envías a tu back-end.

var callback = function(response) {
if(!response.code){
console.log(response.token);
} else {
console.error('Error: ',response.error, 'Code: ', response.code, 'Message: ',response.message);
}
}
kushki.requestTransferToken({
bankId: '1022', // Sólo para Colombia
callbackUrl: 'http://www.testcallbackurl.com/', // No requerido para MX
userType: '1',
documentType: 'NIT',
documentNumber: '171054019',
paymentDesc: 'Descripción de la Tx',
currency: 'USD',
amount: {
subtotalIva: 0, // Configúralo en 0 en caso de que la Tx no tenga impuestos
subtotalIva0: 49.99, // Configura el monto total de la Tx en caso de que no tenga impuestos. De lo contrario, envíalo en 0.
iva: 0, // Envíalo en 0 en caso de que la Tx no tenga impuestos.
extraTaxes: {
propina: 0,
tasaAeroportuaria: 0,
agenciaDeViajes: 0,
iac: 0
}
}
},
callback); // También puedes configurar la función directamente

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 envia el formulario, tu front-end envia un token al endpoint que hayas especificado. Con éste token, deberás realizar una llamada a nuestro endpoint de cobros para iniciar el proceso de cobro.

  • Javascript
  • Python
  • PHP
var settings = {
"async": true,
"crossDomain": true,
"url": "https://api-uat.kushkipagos.com/transfer/v1/init",
"method": "POST",
"headers": {
"content-type": "application/json"
},
"processData": false,
"data": "{\"token\":\"b1d6f46f88fe4759aad9ae0e37cdf905\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":49.99,\"iva\":0,\"extraTaxes\":{\"propina\":0,\"tasaAeroportuaria\":0,\"agenciaDeViajes\":0,\"iac\":0}},\"metadata\":{\"userId\":\"IB344\"}}"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
import requests
url = "https://api-uat.kushkipagos.com/transfer/v1/init"
payload = "{\"token\":\"b1d6f46f88fe4759aad9ae0e37cdf905\",\"amount\":{\"subtotalIva\":0,\"subtotalIva0\":49.99,\"iva\":0,\"extraTaxes\":{\"propina\":0,\"tasaAeroportuaria\":0,\"agenciaDeViajes\":0,\"iac\":0}},\"metadata\":{\"userId\":\"IB344\"}}"
headers = {'content-type': 'application/json'}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"token":"b1d6f46f88fe4759aad9ae0e37cdf905","amount":{"subtotalIva":0,"subtotalIva0":49.99,"iva":0,"extraTaxes":{"propina":0,"tasaAeroportuaria":0,"agenciaDeViajes":0,"iac":0}},"metadata":{"userId":"IB344"}}');
$request->setRequestUrl('https://api-uat.kushkipagos.com/transfer/v1/init');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

De acuerdo a la respuesta del consumo del método para iniciar la transacción, redirecciona al usuario hacia PSE para que tu cliente pueda autenticarse y así autorizar el débito del monto de la transacción del saldo de su cuenta bancaria.

3. Prueba tu integración

Existen números de identificación de prueba que puedes utilizar para asegurarte de que tu integracón esta lista. úsalos, para simular cualquier estado:

  • Transacción aprobada: 123456789
  • Transacción pendiente: 9999999990
  • Transacción en estado rechazado ('NOT_AUTHORIZED'): 100000002
  • Transacción fallida ('FAILED'): Cualquier número de identificación

4. Prepara tu certificación

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

  • El cálculo de los impuestos y el monto total, debe ser el correcto.
  • Mensajes en pantalla de acuerdo a las respuestas de Kushki.
  • Guardar y registrar todas las respuestas de Kushki (requeridas en caso de necesitar soporte).
  • El cliente debe reconocer el método de pago que está utilizando, por lo que debes incluir el logo de PSE. Lo puedes encontrar en: https://descubre.pse.com.co/logos_recaudo_pse/
  • Puedes mostrar el medio de pago, como:
  1. Débito desde cuenta corriente/Ahorros
  2. Débito bancario PSE
  • Evita utilizar los siguientes textos:
  1. Transferencia bancaria
  2. Débito a cuenta
  • Para la redirección no utilices contenedores como Frame, Panel, IFrame, etc. Evite funciones como las ventanas emergentes que son bloqueadas por los navegadores o redirigir en la misma pestaña y/o ventana.
  • En el comprobante de pago, agregue la siguiente información:
  1. Nombre de tu empresa (Nombre o razón social)
  2. NIT de su empresa (NIT)
  3. Descripción del pago
  4. Fecha de la transacción
  5. Estado de la transacción
  6. Código de trazabilidad (CUS)
  7. Número de transacción
  8. Banco
  9. Monto
  • Muestra el estado de la transacción de la siguiente forma:
  1. ProcessorState OK:APROBADA El estado no debe mostrarse en inglés. Adicional, evita el uso de sinónimos, como: exitoso, autorizada, aceptada, pagada, afirmativo, etc.
  2. ProcessorState PENDING:PENDIENTE El estado no debe mostrarse en inglés. Adicional, evita el uso de sinónimos, como: en confirmación, sin resolver, incompleto, etc.
  3. ProcessorState NOT_AUTHORIZED:RECHAZADA El estado no debe mostrarse en inglés. Adicional, evita el uso de sinónimos, como: declinado, cancelado, no aceptado, etc.
  4. ProcessorState FAILED:FALLIDA El estado no debe mostrarse en inglés. Adicional, evita el uso de sinónimos, como: falla, error, etc.
  • Incluir dentro del recibo de pago, un enlace (botón) para acceder a un módulo de consulta en el que se muestren los siguientes datos básicos: CUS, monto, fecha de la transacción, estado actual. Las empresas que no requieran autenticación con nombre de usuario y contraseña para realizar pagos, no tendrán que construir el módulo de consulta.
  • Incluir una opción para descargar e imprimir el recibo.
  • Sí la transacción queda PENDIENTE, NO se debe permitir realizar una nueva transacción, hasta que el estado final de la misma sea aprobado o rechazado.
  • La transacción no puede estar en PENDING:PENDIENTE por más de 21 minutos
  • Todos los estados deben incluir el texto con un número de teléfono y una dirección de correo electrónico de su empresa, donde sus clientes puedan verificar el estado de la transacción.
  • En caso de que recibas correctamente la notificación al Webhook, responde la solicitud con un statusCode 200 e informa tu cliente.
  • El botón “Pagar” se desactiva después del primer clic.
  • El logo de Kushki debe ser visible. Puedes descargarlos aquí.
  • Asegúrate de enviar todas las variables requeridas, especificadas en la referencia de la API

Acepta webhooks

Maneja eventos post-pago de la manera correcta.

Consulta el estado de tus transacciones

Con el token que recibiste desde el front-end, también podrás consultar el estado de las transacciones por medio de nuestra API.