Nequi

Una integración pensada para ser implementada del lado del cliente,  a través de nuestro SDK podrás invocar un servicio  JS para el procesamiento de transacciones  con los usuarios del monedero virtual Nequi. Con este método, mantendrá siempre al usuario dentro de su sitio y controlará todas las respuestas en pantalla.

Prerrequisitos

CCLW
Llaves de conexión al API
Certificado SSL
TLS 1.3 o superior

Base URL de ambientes

Producción
https://secure.paguelofacil.com/
Pruebas
https://sandbox.paguelofacil.com/

1. Incluye SDK en tu sitio

Debes incluir los scripts para poder utilizar nequi dentro de tu sitio web.


<head >
...
<script src="https://secure.paguelofacil.com/HostedFields/vendor/scripts/NEQ/PFScript.js"></script>
<script src="https://secure.paguelofacil.com/HostedFields/vendor/qr-code/qrcode.js"></script>
...
<head >

  

2. Muestra el código QR

Debes incluir una etiqueta div donde se mostrará el código QR de nequi dentro de tu sitio web.


<body>
....
<div id="nequiQR"></div>
.....
</body>

  

3. Añade script de configuración

Debes incluir el script que realizara el proceso de generación QR/Push y procesamiento de pago.


<script>
    //pasar la variable "true" para utilizar plataforma de prueba.
    pfNequi.useAsSandbox(true);

    var mockTest = false;
    if (mockTest) {
        var forceTest = new pfNequi.hostedFields();
        forceTest.dataMerchant.merchant = {
            id: 2,
            name: "Paguelo Facil S.A", //Nombre Comercial registrado en su cuenta.
            legalName: "Paguelo Facil S.A" //Nombre legal registrado en su cuenta.
        };
        forceTest.dataMerchant.service = {
            id: 2, //Credencial Provisto por Paguelofacil
            code: "HFD" //Constante por el tipo de integración
        };

        startMerchantForm(forceTest);
    } else {
        //Utilizar api_key y CCLW suministrado por Paguelofacil
        var api_key = "Mjc3OTNwZjE5MTIwNDExMTIxNg=="; //Token de autorización
        var cclw = "18011D0B9623B253D689FC54A44D1153D1873CA26D23F1E1D90A8F5A6F8BA1B3"; //credenciales del comercio
        pfNequi.openService(api_key, cclw)
            .then(function (merchantSetup) {
                startMerchantForm(merchantSetup);
            }, function (error) {
                console.log(error);
            });
    }

    function startMerchantForm(merchantSetup) {
        var paymentInfo = {
            amount: 1.0,
            description: "Test SDK Nequi",
            email: "alambrito@correo.com",
            phone: "+50767890540"
        };

        var sdk = merchantSetup.init(merchantSetup.dataMerchant, paymentInfo);
        var useQR = true; //utilizar variable "false" para utilizar modo push notifications
        if (useQR) {
            setTimeout(function () {
                sdk.generateQR().then(function (qr) {
                    console.log("qr", qr);
                    //Puede realizar su qr con una libreria propia o usar el JS (qrcode.js) y llamando a la funcion printQR
                    sdk.printQR("nequiQR");
                }, function (error) {
                    console.log("error", error);
                });
            }, 2000);
        } else {
            setTimeout(function () {
                //Envio de notificación a cuenta de nequi "67890540"
                sdk.sendPush("67890540").then(function (data) {
                    console.log("pushSend", data);
                }, function (error) {
                    console.log("error", error);
                });
            }, 2000);
        }

        //Valida el pago recursivamente y registra la TX
        var validPayment = function () {
            sdk.validPayment().then(function (data) {
                if (data) {
                    if (data.validated) {
                        if (data.txSuccess) {

                            //Debes obtener las variables de data.txSuccess y completar su pago
                            console.log("Registro de Pago existoso", data.txSuccess);
                        } else {

                            //Informe el usuario del error e indique volver a intentarlo
                            console.log("Pago Declinado", data.txError);
                        }
                    } else {
                        console.log("Reenvia", data);
                        setTimeout(function () {
                            validPayment();
                        }, 1000);
                    }
                }
            }, function (error) {
                console.log("error valid", error);
            });
        };
        
        


        setTimeout(function () {
            validPayment();
        }, 5000);
    }
</script>

  

4. Valida la respuesta

Debes validar correctamente el pago exitoso dentro de tu respuesta de transacción.


<script>
        ...
        var validPayment = function () {
            sdk.validPayment().then(function (data) {
                if (data) {
                    if (data.validated) {
                        if (data.txSuccess) {
                          if(data.txSuccess.status == 1){
                             //Scripts para pago aprobado
                          }
                        } else {
                           ....
                        }
                    } else {
                       ....
                    }
                }
            }, function (error) {
                ....
            });
        };
        ...
</script>

Cancela el pago del usuario

Sí no recibes una respuesta del pago en  un tiempo determinado, o el usuario cierra la ventana del navegador es posible cancelar la solicitud, de este modo cuando el usuario quiera pagar en app de Nequi se le informará que esta solicitud fue cancelada.


<script>
        ...
       //voidPayment(); cancela la solicitud de pago

        var voidPayment = function () {
            sdk.voidPayment().then(function (data) {

            }, function (error) {
            });
        };
        ...
</script>

¿Uso Push o QR?

Debes decidir si utilizar ambas formas (push y QR), o solo unas de ellas dependiendo de si tu web recibe mayor visita por dispositivos móviles o web

Recomendaciones

  • Informa a tu usuario en cada proceso.
  • Coloca una ayuda en caso de dudas.