
-
Colombia
-
Panamá
Colombia
Panamá
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:
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:
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:
Los requisitos con que deben contar los servicios son:
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.
A continuación se detalla las firmas y estándar de cada servicio:
Método HTTP: GET
--- no body ---
OK
{
"errors": [
{
"code": "20-07C", //Código del error,
"description": "Technical Error", //Descripción del error
}
]
}
Método HTTP: GET
Nombre | Descripción |
messageId | Identificador único de la petición |
El resto de parámetros son dinámicos para cada negocio/aliado y necesarios para la consulta.
Ej:
Nombre | Descripción |
documentType | Tipo de documento del cliente |
contractNumber | Número de contrato |
... |
{
"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.
{
"errors": [
{
"code": "20-05C", //Código del error,
"description": "Bad params", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "Incorrect credentials.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "You do not have permissions to access the resource.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-08C", //Código del error,
"description": "Not Found", //Descripción del error
}
]
}
{
"errors": [
{
"code": "", //Código del error en su sistema,
"description": "", //Descripción del error
}
]
}
{
"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.
Método HTTP: POST
content-type | application/json |
{
"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"
}
}
{
"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.
{
"errors": [
{
"code": "20-05C", //Código del error,
"description": "Bad params", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "Incorrect credentials.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "You do not have permissions to access the resource.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-08C", //Código del error,
"description": "Not Found", //Descripción del error
}
]
}
{
"errors": [
{
"code": "", //Código del error en su sistema,
"description": "", //Descripción del error
}
]
}
{
"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.
Método HTTP: GET
Nombre | Descripción |
messageId | Identificador único de la petición |
paymentMessageId | Id de la notificación de recaudo a consultar |
{
"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:
statusPayment | Descripción |
0 | Pago realizado con éxito |
1 | Falló el pago |
2 | Pendiente por confirmación, reintentar |
3 | El pago fue reversado |
{
"errors": [
{
"code": "20-05C", //Código del error,
"description": "Bad params", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "Incorrect credentials.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "You do not have permissions to access the resource.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-08C", //Código del error,
"description": "Not Found", //Descripción del error
}
]
}
{
"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.
Método HTTP: PUT
content-type | application/json |
{
"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.
{
"statusPayment": "3", //Resultado exitoso de la anulación
}
{
"errors": [
{
"code": "20-05C", //Código del error,
"description": "Bad params", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "Incorrect credentials.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10C", //Código del error,
"description": "You do not have permissions to access the resource.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-08C", //Código del error,
"description": "Not Found", //Descripción del error
}
]
}
{
"errors": [
{
"code": "", //Código del error en su sistema,
"description": "", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-07C", //Código del error,
"description": "Technical Error", //Descripción del error
}
]
}
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
{
"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:
statusPayment | Descripción |
0 | Pago realizado con éxito |
1 | Falló el pago |
2 | Pendiente por confirmación, reintentar |
3 | El pago fue reversado |
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.
OK
{
"errors": [
{
"code": "20-05A", //Código del error,
"description": "Bad params", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10A", //Código del error,
"description": "Incorrect credentials.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-10A", //Código del error,
"description": "You do not have permissions to access the resource.", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-08A", //Código del error,
"description": "Not Found", //Descripción del error
}
]
}
{
"errors": [
{
"code": "20-07C", //Código del error,
"description": "Technical Error", //Descripción del error
}
]
}
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