Recibe transferencias bancarias

25 octubre 2023

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

Permite que tus clientes aprovechen el saldo disponible en su cuenta bancaria para adquirir tus productos o servicios desde tu app iOS, a través de PSE o PSE Avanza. Para lograrlo, debes habilitar el listado de bancos disponibles en Colombia, obtener los datos básicos 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 para PSE (Versión 1.0) que integrarás es el siguiente:

El flujo de pago para PSE Avanza (Versión 2.0) que integrarás es el siguiente:

Con esta versión mejoramos la experiencia de usuario permitiendo a tus clientes comprar en menos pasos.

1. Configura tu app

La responsabilidad de la app es recolectar los datos básicos de pago del usuario, tokenizar esa información a través de los servidores de Kushki y enviarla a tu back-end para iniciar el proceso de pago.

Instala el SDK de Kushki

Vamos a utilizar CocoaPods para instalarlo. Sí 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 listado de bancos

Antes de generar el token, necesitas cargar el listado completo de bancos disponibles, 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.requestBankList(callback); // Also you can set the function directly

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

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

private func requestKushkiTransferToken(amount: Amount, callbackUrl:String, userType:String, documentType:String, documentNumber:String, email:String, description:String) {
        let publicMerchantId = "publicMerchantId"
        let kushki = Kushki(publicMerchantId: publicMerchantId,
                            currency: "USD",
                            environment: KushkiEnvironment.testing)
        kushki.requestTransferToken(amount: amount, callbackUrl: callbackUrl, userType: userType, documentType: documentType, documentNumber: documentNumber, email: email,paymentDescription: description) { transaction in
            let message = transaction.isSuccessful() ?
                transaction.token : transaction.code + ": " + transaction.message
            //                transaction.code + ": " + transaction.message
            DispatchQueue.main.async(execute: {
                let alert = UIAlertController(title: "Kushki Token",
                                              message: message,
                                              preferredStyle: UIAlertController.Style.alert)
                alert.addAction(UIAlertAction(title: "Ok", style: .default))
                self.present(alert, animated: true)
            })
            self.ResponseView.text = "Response transfer token: \n\n" + 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 transfiere un token al endpoint que hayas especificado. Con este token, deberás realizar una llamada a nuestro endpoint de cobros para iniciar el proceso de cobro.

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/transfer/v1/init', // Ambiente de prueba
       headers: {
           'content-type': 'application/json'
       },
       body: {
           "token": "b1d6f46f88fe4759aad9ae0e37cdf905",
           "amount": {
               "subtotalIva": 0,
               "subtotalIva0": 90000,
               "iva": 0,
           },
           "contactDetails": {
               "fullName": "John Doe",
               "address": "Centro 123",
               "phoneNumber": "3912345678",
               "email": "test@kushkipagos.com",
           },
           "metadata": {
                  "userId": "IB344"
           }
    }
           };
           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/transfer/v1/init"

payload = "{\n  \"token\":\"b1d6f46f88fe4759aad9ae0e37cdf905\",\n  \"amount\": {\n  \"subtotalIva\": 0,\n  \"subtotalIva0\": 90000,\n  \"iva\": 0,\n  }\n  },\n  \"contactDetails\": {\n  \"fullName\": \"John Doe\",\n  \"address\": \"Centro 123\",\n  \"phoneNumber\": \"3912345678\"\n  },\n  \"email\": \"test@kushkipagos.com\"\n  },\n  \"metadata\": {\n  \"userId\": \"IB344\"\n  }\n}"
headers = {'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": "b1d6f46f88fe4759aad9ae0e37cdf905",
 "amount": {
   "subtotalIva": 0,
   "subtotalIva0": 90000,
   "iva": 0,
 },
 "contactDetails": {
   "fullName": "John Doe",
   "address": "Centro 123",
   "email": "test@kushkipagos.com",
   "phoneNumber": "3912345678"
 },
 "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();

• Para PSE (Versión 1.0)

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

• Para PSE Avanza (Versión 2.0)

De acuerdo a la respuesta del consumo del método para iniciar la transacción, redirecciona al usuario hacia la URL que te retorna Kushki para que pueda autenticarse en el portal virtual de su entidad bancaria y así autorizar el débito del monto de la transacción del saldo de su cuenta bancaria.

Muestra el resultado de la transacción

Una vez terminado el pago en el portal de PSE (Versión 1.0) o en el portal bancario (Versión 2.0) , se retornará el cliente con una llamada GET a la callbackUrl que hayas especificado al solicitar el token.

Junto con la URL de retorno te enviaremos en la ruta el token de la transacción, con el cual puedes verificar el estado de la transacción utilizando este endpoint. Además, obtendrás la información necesaria para el comprobante de pago de tu cliente.

Por ejemplo, para callbackUrl = 'http://www.example.com' se retornará el cliente a:

GET https://www.example.com/?token=26735cbb653a421ba7138eb515e0ab1d

donde token es igual a 26735cbb653a421ba7138eb515e0ab1d

De acuerdo con la respuesta que recibas del estado de la transacción, muestra al usuario una pantalla de éxito o fracaso para informar al cliente si el pago se realizó correctamente o si hubo un error.

3. Prueba tu integración

Existen números de identificación de prueba que puedes utilizar para asegurarte de que tu integración está lista. Úsalos para simular cualquier estado:

• Transacción aprobada: 123456789
• Transacción pendiente: 999999990
• 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.
• Muestra tus mensajes en pantalla de acuerdo con las respuestas de Kushki.
• Guarda y registra 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.
• Puedes mostrar el medio de pago, como:
  • Débito desde cuenta corriente/Ahorros
  • Débito bancario PSE
• Evita utilizar los siguientes textos:
  • Transferencia bancaria
  • 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:
  • Nombre de su empresa (Nombre o razón social)
  • NIT de su empresa (NIT)
  • Descripción del pago
  • Fecha de la transacción
  • Estado de la transacción
  • Código de trazabilidad (CUS)
  • Número de transacción
  • Banco
  • Monto

• Muestra el estado de la transacción de la siguiente forma:
  • 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.
  • 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.
  • 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.
  • 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.
• Si la transacción queda PENDIENTE, NO se debe permitir realizar una nueva transacción hasta que el estado final de la misma sea aprobada o rechazada.
• 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 tu empresa, donde tus 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 a tu cliente.
• El botón ”Pagar” se desactiva después del primer clic.
• El logo de Kushki debe ser visible para el cliente. Puedes encontrar nuestro logo en varios formatos aquí.
• Asegúrate de enviar todas las variables requeridas, especificadas en la referencia de la API.