¿Qué es Recaudos Nequi?

Introducción

Antes de que hagamos un desarrollo y comiences a trabajar con esta documentación, cuenta porfa con la asesoría de nuestro Equipo Comercial, para que analicen si la alianza con Nequi es posible.

Si necesitas comunicarte con nuestro Equipo Comercial, escríbenos porfa a negocios@nequi.co

El producto le permite de una forma sencilla integrarse con nuestra plataforma para recibir pagos, recaudos o recargas de nuestros usuarios desde el Armario de Nequi.

Este mecanismo de integración le permite realizar un recaudo con o sin validación en base de datos y conocer en línea cada que un usuario realiza una transacción otorgándole a su sistema la capacidad de controlar y validar los pagos hechos desde nuestra plataforma.

Todos los recaudos del día se consolidan en nuestro sistema y se acreditan, luego de descontar la comisión pactada e IVA, al día siguiente en su cuenta Bancolombia, enviando adicionalmente un reporte de las transacciones en formato AsoBancaria 2001, AsoBancaria 2011 o CSV con columnas personalizadas a un correo electrónico, SFTP o bucket en S3.

Para integrarse con nuestra plataforma cuenta con distintas opciones según como opere su recaudo. En términos generales deberá exponernos los siguientes servicios o capacidades de su sistema:

• Servicio de consulta de estado de salud: Este servicio tiene como objetivo permitirle a la plataforma Nequi consultar el estado de su sistema y habilitar el servicio a usuarios Nequi o desactivarlo mientras una contingencia o falla.
• Consulta de información, saldo o existencia de cliente dentro de su sistema: Este servicio es opcional, su objetivo es agregar una consulta o validación en el flujo del recaudo para retornar información que hace parte de la transacción o el valor a recaudar, también en algunos casos es usado para validar la información dada por el usuario si corresponda a un recaudo que exista dentro de su sistema  o si corresponda a un cliente de su sistema.
• Notificación del recaudo: Este servicio tiene como objetivo notificarle a su sistema que se ha realizado un recaudo dentro de nuestra plataforma. Además de los datos básicos del recaudo (fecha, identificador, valor, cliente), puede solicitar a Nequi que en este servicio se le envíe a su sistema hasta 6 valores de referencia que se capturen en el formulario de recaudo dentro del Armario de Nequi y que se agreguen a los reportes (si aplica), O incluso si el servicio anterior de consulta fue implementado y parte de los datos que retorna desea se guarden dentro de la transacción como alguna de esas 6 referencias, solo es necesario nos indique en la etapa de diseño de la experiencia que tendrá con Nequi y podrá gestionar con el asesor comercial Nequi que lo esté acompañando.
• Consulta del estado de un recaudo: Este servicio tiene como objetivo permitirle a nuestra plataforma consultar con base al identificador de una notificación de recaudo enviado por nuestro sistema si la notificación se logró procesar de forma exitosa, no existe o fue rechazada en su sistema. Este servicio es requerido para lograr cerrar el flujo de la transacción en caso el servicio de Notificación de recaudo arroje timeout o error 500, reintentando nuestra plataforma el consumo de este servicio de consulta durante X veces cada Y segundos. (También se puede implementar un esquema de webhook basado en nuestro estándar, para que su sistema notifique pro activamente de manera proactiva a nuestra plataforma cuando la transacción se procese correctamente o tenga fallas y así evitar la consulta recurrente desde Nequi, aplicando solo en caso que no recibamos en N segundos una notificación de su sistema sobre esa notificación de recaudo).
• Servicio de reverso/anulación de la notificación  de un recaudo: Este servicio es opcional según el funcionamiento de su sistema y el flujo de la transacción, en caso de ser posible implementarlo, este tiene como objetivo permitir a la plataforma Nequi reversar/anular la notificación de un recaudo enviado por Nequi, para que su sistema interprete la transacción de pago asociada al reverso como fallida y no la procese dentro de su sistema. Este servicio solo será usado ante fallas técnicas sea dentro de Nequi o consumiendo el servicio de notificación de recaudo anteriormente descrito que deberá exponer.

Flujos de secuencia para implementar el estándar

Consulta de salud o disponibilidad del ambiente:

El flujo de este servicio no interviene en la transacción pero si en el acceso del usuario a la opción a través del Armario de Nequi:

Posibles modelos de integración para el recaudo

Con base en las capacidades o servicios descritos se pueden presentar dos escenarios de recaudo:

Recaudo sin base de datos:

En este escenario el servicio de consulta o validación previa al recaudo no es requerido y en el recaudo se hace con los datos que ingrese el usuario, éste debe conoce el valor que debe pagar y lo ingresa directamente en la experiencia de pago desde la App Nequi: Ej. Recarga de Celular.

Recaudo con base de datos:

En este modelo el usuario ingresa la información inicial para el recaudo y luego se consume el servicio de consulta o verificación expuesto bajo este estándar:

Ante los siguientes escenarios en el proceso de notificación de recaudo puede se presenten errores técnicos o fallas de comunicación que impidan a la plataforma Nequi conocer el resultado final del procesamiento del recaudo en su servicio. Para esto existen dos modelos, con servicio de consulta o servicio de reverso, los cuales permiten cerrar el flujo de la transacción e informar al usuario el estado de la transacción oportunamente.

Para su integración, tiene la opción de seleccionar si el recaudo debe ser con o sin base de datos, y si van a implementar servicio de consulta o reverso. Además, existe la opción que su sistema consuma un servicio nuestro (Webhook) para notificar el resultado del procesamiento  del recaudo en su sistema y ser más costo/eficientes en el consumo del servicio de consulta que exponga:

Teniendo claro el modelo de integración y los servicios que desea implementar, es necesario tener presente los siguientes requisitos técnicos:

Requisitos de los servicios

Los requisitos con que deben contar los servicios son:

• La conexión debe ser mediante VPN o por Internet.
• Los servicios deben ser REST y expuestos usando HTTPS y TLS 1.2.
• El mecanismo de autenticación de las APIs debe ser OAuth, JWT, JWS (By Nequi) o si usa VPN es posible usar Basic Authentication.
• Los payload de los request y response de sus servicios deben estar acorde a la documentación y especificación de Nequi, si no cumplen no se podrá realizar la integración.
• No podrán tener un timeout superior a 25 segundos.
• Puede elegir el path y dominio que desee para sus servicios siempre que cumplan con la estructura de mensajes y método HTTP REST definido.
• Solo se podrán requerir cabeceras adicionales a las establecidas si son de valor estático y no cambia entre las peticiones. No aplica para las cabeceras requeridas para la autenticación de los servicios.

Además, tenga presente que sus servicios y/o sistema debe cumplir las condiciones operativas y de soporte del Servicio de recaudo a través de la App Nequi especificadas en el anexo técnico de los términos y condiciones que firmarán una vez concretada la alianza.

Especificaciones de los servicios

A continuación se detalla las firmas y estándar de cada servicio:

Consulta de estado de salud

Método HTTP: GET

Request:

    
        --- no body  ---

Response:

• HTTP 200:

    OK

• HTTP 500 (El servicio no esta disponible):

    
        {
            "errors": [
               {
                 "code": "20-07C", //Código del error,
                 "description": "Technical Error", //Descripción del error
               }
             ]
        }
    

Consulta de información, saldo, facturas o existencia de cliente dentro de su sistema

Método HTTP: GET

Query Params:

• Requeridos:​

El resto de parámetros son dinámicos para cada negocio/aliado y necesarios para la consulta.

Ej:

Response:

• HTTP 200:

    
        {
            "products": [ //Array de objetos con las ofertas de pago/recarga/facturas que devuelve su sistema
               {
                 // Datos a enviar para realizar el pago o qué deben ser graficados al usuario.
                 "cardNumber": 6136977,
                 "id": "1",
               }
             ]
        }
   

Algunos servicios de terceros devuelven en la consulta el valor exacto a pagar, este campo es identificado con el nombre/key "value" dentro del arreglo de products, de no ser un dato que devuelva el servicio, queda a elección del usuario decidir cuanto pagar. Si el arreglo de products solo trae un registro no se le mostrará al usuario la pantalla de selección y se le enviará directamente al pago de ese registro. Si su cliente si existe dentro de su sistema pero no tiene nada pendiente por pagar, retornar el arreglo "products" vacío. 

• HTTP 400 (Parámetros incorrectos):

{
  "errors": [
    	{
      		"code": "20-05C", //Código del error,
      		"description": "Bad params", //Descripción del error
  		}
  ]
}

• HTTP 401 (Credenciales invalidas):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "Incorrect credentials.", //Descripción del error
  		}
  ]
}

• HTTP 403 (No tiene acceso a este servicio):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "You do not have permissions to access the resource.", //Descripción del error
  		}
  ]
}

• HTTP 404 (Con los datos enviados no se logró encontrar información en su sistema):

{
  "errors": [
    	{
      		"code": "20-08C", //Código del error,
      		"description": "Not Found", //Descripción del error
  		}
  ]
}

• HTTP 420 (No se pudo realizar la consulta por alguna regla de su negocio):

{
  "errors": [
    	{
      		"code": "", //Código del error en su sistema,
      		"description": "", //Descripción del error
  		}
  ]
}

• HTTP 500 (El servicio no esta disponible):

{
  "errors": [
    	{
      		"code": "20-07C", //Código del error,
      		"description": "Technical Error", //Descripción del error
  		}
  ]
}

Recuerde en el formulario para la integración compartido por el comercial NEQUI definir cuáles serían los títulos en la experiencia, cuáles de estos campos deben ser mostrados al usuario durante el recaudo en la App Nequi y definir cuáles pertenecen a las 6 referencias que puede guardar en la transacción y le serán enviados en los reportes.

Tenga presente que algunos estándares como AsoBancaria no permiten tantas referencias, para este tipo de reportes solo podrán enviarse las que el estándar tenga definidas. En reportes CSV personalizados no hay esta restricción.

Notificación del recaudo

Método HTTP: POST

Headers:

Request:

{
    "messageId": "123456789", //Código único de transacción
    "value": "1", //Valor a pagar
    "fields": { //Campos necesarios para el pago (Usualmente obtenidos desde el servicio de consulta)
       "cardNumber": 6136977
       "id": 1
       ...
     },
    "asynchronous": true, //Indica la manera en la cual se procesara la petición (true/false)
    "reportUrl": { //Contiene los datos de la url a la cual se realizara el reporte del pago, solo requerido cuando asynchronous === true. Sino se envia y asynchronous === true se debe notificar al endpoint default de Nequi especificado más abajo. 
        "host": "l5o5ir2tv7.execute-api.us-east-1.amazonaws.com",
        "path": "/qa/test",
        "port": "443"
    }
}

Response:

• HTTP 200:

{
  "paymentMessageId": "123456789", //Corresponde al messageId asociado al pago enviado en la notificación del recaudo
  "fields": { //Campos devueltos por el tercero, necesarios para consulta y reverso
    "externaltransactionId": "123456789"
    "transactionDate": "2020-02-20T14:19:10"
  }  
}

La información devuelta en "fields", es información de su sistema referente a la confirmación del recaudo y puede variar según el producto solicitado.

• HTTP 400 (Parámetros incorrectos):

{
  "errors": [
    	{
      		"code": "20-05C", //Código del error,
      		"description": "Bad params", //Descripción del error
  		}
  ]
}

• HTTP 401 (Credenciales invalidas):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "Incorrect credentials.", //Descripción del error
  		}
  ]
}

• HTTP 403 (No tiene acceso a este servicio):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "You do not have permissions to access the resource.", //Descripción del error
  		}
  ]
}

• HTTP 404 (Con los datos enviados no se logró encontrar información en su sistema que permita hacer el recaudo):

{
  "errors": [
    	{
      		"code": "20-08C", //Código del error,
      		"description": "Not Found", //Descripción del error
  		}
  ]
}

• HTTP 420 (No se pudo realizar la transacción por alguna regla de su negocio):

{
  "errors": [
    	{
      		"code": "", //Código del error en su sistema,
      		"description": "", //Descripción del error
  		}
  ]
}

• HTTP 500 (El servicio no esta disponible):

{
  "errors": [
    	{
      		"code": "20-07C", //Código del error,
      		"description": "Technical Error", //Descripción del error
  		}
  ]
}

Además, tenga presente notificar a su comercial Nequi si necesita que, luego de ejecutado el pago, alguna de la información que retorna este servicio sea agregada a la transacción para visualización en el movimiento del usuario o en los reportes.

Consulta del estado de un recaudo

Método HTTP: GET

Query Params:

• Requeridos:

Response:

• HTTP 200:

{
  "data": { //Información adicional del recaudo
    "externaltransactionId": 2570364,
    "transactionId": 4002700
  },
  "statusPayment": "0", //Estado del procesamiento de la transacción
  "paymentMessageId": "1234567" //Id de la notificación del recaudo enviado por Nequi
}

La información devuelta en "data", es información de su sistema referente a la confirmación del recaudo y puede variar según el producto solicitado.

"data.statusPayment" indica el estado de la transacción. Posibles valores:

• HTTP 400 (Parámetros incorrectos):

{
  "errors": [
    	{
      		"code": "20-05C", //Código del error,
      		"description": "Bad params", //Descripción del error
  		}
  ]
}

• HTTP 401 (Credenciales invalidas):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "Incorrect credentials.", //Descripción del error
  		}
  ]
}

• HTTP 403 (No tiene acceso a este servicio):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "You do not have permissions to access the resource.", //Descripción del error
  		}
  ]
}

• HTTP 404 (Con los datos enviados "paymentMessageId" no se logró encontrar una notificación de recaudo):

{
  "errors": [
    	{
      		"code": "20-08C", //Código del error,
      		"description": "Not Found", //Descripción del error
  		}
  ]
}

• HTTP 500 (El servicio no esta disponible):

{
  "errors": [
    	{
      		"code": "20-07C", //Código del error,
      		"description": "Technical Error", //Descripción del error
  		}
  ]
}

Además, tenga presente notificar a su comercial Nequi si necesita que, luego de ejecutado el pago, alguna de la información que retorna este servicio sea agregada a la transacción para visualización en el movimiento del usuario o en los reportes.

Servicio de reverso/anulación de la notificación  de un recaudo:

Método HTTP: PUT

Headers:

Request:

{
    "messageId": "1581954124512", //Código único de transacción
    "value": "1", //Valor de la transacción realizada
    "paymentMessageId": "123456789" //Message ID al momento de realizar el pago
    "fields": { //Campos necesarios para el realizar el reverso (Varian según el producto a reversar)
        "externalTransactionId": 4002621
	}
}

Los atributos "value" y "paymentMessageId" deben corresponder con los datos enviados en la petición de la notificación del recaudo, de lo contrario el servicio debe fallar.

La información del atributo "fields" corresponde al atributo "data" de la respuesta del servicio de pago.

Response:

• HTTP 200:

{
    "statusPayment": "3", //Resultado exitoso de la anulación
}

• HTTP 400 (Parámetros incorrectos):

{
  "errors": [
    	{
      		"code": "20-05C", //Código del error,
      		"description": "Bad params", //Descripción del error
  		}
  ]
}

• HTTP 401 (Credenciales invalidas):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "Incorrect credentials.", //Descripción del error
  		}
  ]
}

• HTTP 403 (No tiene acceso a este servicio):

{
  "errors": [
    	{
      		"code": "20-10C", //Código del error,
      		"description": "You do not have permissions to access the resource.", //Descripción del error
  		}
  ]
}

• HTTP 404 (Con los datos enviados "paymentMessageId" y "value" no se logró encontrar una notificación de recaudo para reversar):

{
  "errors": [
    	{
      		"code": "20-08C", //Código del error,
      		"description": "Not Found", //Descripción del error
  		}
  ]
}

• HTTP 420 (No se pudo reversar la transacción por alguna regla de su negocio):

{
  "errors": [
    	{
      		"code": "", //Código del error en su sistema,
      		"description": "", //Descripción del error
  		}
  ]
}

• HTTP 500 (El servicio no esta disponible):

{
  "errors": [
    	{
      		"code": "20-07C", //Código del error,
      		"description": "Technical Error", //Descripción del error
  		}
  ]
}

Especificación para el Webhook

Para integrarse bajo el modelo de Webhook es requerido envíe sus notificaciones a los siguientes endpoints:

QA: PENDIENTE

PDN: PENDIENTE

Método HTTP: POST

Request:

{
  "data": { //Información adicional del recaudo
            "externaltransactionId": 2570364,
            "transactionId": 4002700
  },
  "statusPayment": "0", //Estado del procesamiento de la transacción
  "paymentMessageId": "1234567", //Id de la notificación del recaudo enviado por Nequi
  "code": "NIT_1_00" //Identificador del comercio dentro de Nequi, registro en Negocios Nequi.
  "productName": "RECARGA", //Identifica el producto por si existen multiples servicios con el mismo aliado
}

Los posibles valores del campo statusPayment son:

Además, tenga presente notificar a su comercial Nequi si necesita que, luego de notificado el procesamiento del recaudo, alguna de la información que envío a nuestro webhook sea agregada a la transacción para visualización en el movimiento del usuario o en los reportes.

Este servicio funciona bajo el esquema "fire and forget" entonces siempre recibirá respuesta correcta con código HTTP 200.

La seguridad de este webhook esta basada en la guía anexa para el firmado de peticiones hacia el webhook y Nequi le entregará un secreto/llave privada y appId con el cual deberá firmarlas.

Response NEQUI:

• HTTP 200:

OK

• HTTP 400 (Parámetros incorrectos):

{
  "errors": [
    	{
      		"code": "20-05A", //Código del error,
      		"description": "Bad params", //Descripción del error
  		}
  ]
}

• HTTP 401 (Credenciales invalidas):

{
  "errors": [
    	{
      		"code": "20-10A", //Código del error,
      		"description": "Incorrect credentials.", //Descripción del error
  		}
  ]
}

• HTTP 403 (No tiene acceso a este servicio):

{
  "errors": [
    	{
      		"code": "20-10A", //Código del error,
      		"description": "You do not have permissions to access the resource.", //Descripción del error
  		}
  ]
}

• HTTP 404 (Con los datos enviados "paymentMessageId" no se logró encontrar una notificación de recaudo):

{
  "errors": [
    	{
      		"code": "20-08A", //Código del error,
      		"description": "Not Found", //Descripción del error
  		}
  ]
}

• HTTP 500 (El servicio no esta disponible):

{
  "errors": [
    	{
      		"code": "20-07C", //Código del error,
      		"description": "Technical Error", //Descripción del error
  		}
  ]
}

Pasos a seguir

Con la información anterior puede diseñar e implementar los servicios para integrarse con el Armario Nequi y recibir recaudos, tenga presente que adicional a este documento debe seguir todos los pasos y cumplir con todos los requisitos indicados por el comercial Nequi, si aún no cuenta con uno escríbenos a negocios@nequi.co